Skip to content

Notes on: Write the Docs Atlantic 2024

Conference notes on Write the Docs Atlantic 2024. This post has two functions: notes for future me, and knowledge sharing.

DevOps your Docs by Lorna Jane

This was a brilliant, clear introduction to key concepts in docs as code and devops. If you're new to this approach to documentation, I highly recommend this talk to help understand the 'why' behind a lot of ops practices, as well as the key steps and types of tools.

Talk outline:

  • Prereqs to make use of the approaches in this talk: lightweight markup, Git.
  • Automation: run locally for immeditate feedback -> include tool with every PR (pull request) -> publish with confidence.
  • How to automate:
    1. Pick a tool you can run anywhere.
    2. Run it locally and configure settings.
    3. Add instructions and configuration to repo.
    4. Automate for every PR.
  • Continuous integration: this is step 4.
    • Make sure to test fail conditions!
  • Example of a GitHub Action.
  • Automation thinking:
    • Error or warning? How serious is the issue?
    • No output means everything is fine (CLI tools are 'grumpy', they'll tell you about problems but they don't give compliments)
    • Document the tools used and their purpose: knowledge sharing, empowering the team.
    • Golden rule: never ignore a failing test. If you don't need the test, turn it off. Don't create the habit of ignoring failed tests.
  • DocOps tools:
    • Link checking
    • Validation/formatting tools
      • Consistent whitespace and layout: be opinionated, enforce consistency. Lowers cognitive load.
      • Consider automatic formatting tools.
      • Syntax checking for your markup language.
    • Preview builds: every PR should build a preview. Tests it in the cloud environment, useful to share, helpful for reviews.
    • Vale: quality assurance for the written word. Spellchecks, style guide checks, terminology, clarity guidance . . .
  • Invest time and energy:
    • All tools should be available locally for fast feedback.
    • It's about documentarian efficiency:
      • Invest in the skills of the team.
      • Identify and share resources.
      • Set aside time for hands-on practice.

Sketchnote by Dennis Dawson:

"A sketchnote: a visual summary of the talk"

RAGs to Riches: How Our Content Affects Retrieval Augmented Generation by Manny Silva

This talk was a speedy run through key concepts and components of RAG. My note-taking wasn't able to keep up with every detail. I highly recommend watching the talk for a lot more detail.

Talk outline:

  • Introduction: LLMs have a knowledge problem, docs can help.
  • The evolution of LLMs: from rule-based systems to neural networks.
  • Problems: LLMs are trained on public docs, but this knowledge isn't kept up to date (in the model). Models can hallucinate.
  • Introduction to RAG: RAG dynamically provides LLMs with relevant info at runtime. Can add domain-specific info. Solves the problem of knowledge becoming outdated. Helps reduce hallucinations. Can also cite sources.
  • Vector-based RAG: commonest implementation. Convert docs and queries into numerical representations, then perform similarity searches. Efficient, language-agnostic, scales well. Can miss context and nuance, and can struggle with long-form content. No known unknowns (it doesn't know what it doesn't know).
  • Graph-based RAG: combines symbolic and neural approaches. Need to create a graph structure from your knowledge: this can be complex.
  • Documentation best practices for RAG:
    • Structure: clear descriptive headings, logical organization of information, use of summary paragraphs, consistent formatting.
    • Metadata and tagging: consistent use, hierarchical tagging systems, linking related content.
    • Balance human and machine readability: write for clarity and concision, use machine-readable formats, maintain glossary.
    • My note: this echoes other talks I've seen on writing for AI. Basically, be a good tech writer: quality documentation is good for both human users and RAG.
  • Example: implementing RAG at Skyflow.
    • My note: this is especially interesting as it not only supported chat, but also helped draft new content based on templates.
  • Emerging trends: hybrid approaches (graph and vector), multi-modal RAG (images, video), self-updating knowledge bases, integrations with large action models.

Sketchnote by Dennis Dawson:

"A sketchnote: a visual summary of the talk"

Day 1 Lightning talks

A lightning talk is a very short talk, up to 5 minutes, where you share an idea, concept, or a bit of information you find interesting. They’re quick, easy, and a great way to speak in front of an audience for the first time. (source)

I've linked to speaker profiles where possible, but not all speakers provided full names or profile images to help track them down.

  • Ariel Kaiser: You just spilled a whole pallet of milk at work. What now?
    • Sometimes you make mistakes, and they will have consequences.
    • Stop, get help, accept what's coming, take responsibility.
  • Maggie H: Moss and Research Habits: Learning where to stop researching and get writing!
    • You'll never feel like you did enough research.
    • Ironically there were four minutes on moss and less than 60 seconds on the main takeaways of this talk.
  • Dennis Dawson: Beyond Bullet Points - Tips for Presenting with Slides
    • Font size > 18pt
    • Fewest words possible
    • One idea per slide
    • Recommends Cliff Atkinson's Beyond Bullet Points (and it does sound awesome!)
  • Abi Sutherland: A Documentation Carol: Scrooge has tech writing lessons for us all
    • Focus on the current product or system - what the user has in front of them. Not the past or future of the product.
    • Listen to your fellow documentarians; don't reinvent the wheel.
    • Think about user needs.
    • Always be asking questions.
    • Build/join communities.
  • Rose Williams and Arnold (the dog): Meet a foster dog, the value of fostering and adopting senior animals

A talk that came with a free planning template! The talk provided a clear methodical walkthrough of how OutSystems does docs planning. An interesting insight into how companies with established processes and teams can work, and a good starting point for thinking about your own planning process.

Talk outline:

  • Feature-driven docs: not user-centric, don't reflect user journey.
  • Write a user-centric documentation plan before writing docs.
    • When they did this, metrics improved, as did collaboration and understanding.
  • What is a documentation plan?
    • Identifies the target audience, needs of audience, what content satisfies those needs, the content structure, and priorities.
  • How to create a documentation plan:
    1. Identify the purpose of the product/feature: use product and design materials. What problem does it solve? Who does it affect, when, and where? And what is the proposed solution? How does it add value and what are its intended outcomes?
    2. Identify the audience.
    3. Understand the journey: how does the user interact with the product/feature?
    4. Identify the use cases.
      • My note: are they using 'use case' in its normal sense? I would have put this before user journey.
    5. Evaluate the docs scope: what content already exists, what needs updating, where is new content needed. And what pre-existing knowledge can we assume users have.
    6. Identify content types: concept/overview, process, procedure, best practices, troubleshooting, reference.
      • My note: unclear on distinction between process and procedure docs here.
    7. Prioritize: focus on what helps users the most. Make sure outdated docs are updated.
  • Documentation plan template: a Google doc provided by the speakers.
  • Challenges:
    • Difficulty understanding the product.
    • Too many materials.
    • Outdated information from SMEs.
    • Overcomplicating and overwhelming users.
    • Slow responses from SMEs.
  • To overcome challenges:
    • Collaborate early
    • Continuous inquiry
    • Understand the user journey
    • Organize your research
    • Conduct brainstorming sessions
  • Metrics: adopting this approach to documentation planning coincided with an improvement in usefulness metrics.

Sketchnote by Dennis Dawson:

"A sketchnote: a visual summary of the talk"

From morphemes to manuscripts: how linguistics can make you a better writer by Chloe Guttmann

This talk gets into the 'why' behind some tech writing conventions. As always, a linguistics talk makes me want to learn a lot more about linguistics.

Talk outline:

  • What is linguistics? The scientific study of language and its structure.
    • Relevant to documentarians because: helps communicate efficienty and accessibly (especially in translation); understant the why behind rules; develop critical thinking.
  • Semantics: the branch of linguistics and logic concerned with meaning.
    • Vague: non-precise, fuzzy meanings. 'The data uploads quickly' ('quickly' is vague).
    • Ambiguous: multiple distinct meanings.
      • 'Accounts for the part of nodes that are not allocated to run workloads' (Is 'accounts' a noun or verb?)
      • Syntactic (structural) ambiguity: 'Do not use a default with a wider IP address range' (Does this mean 'don't use an X that has a Y' or 'don't use an X alongside a Y')
      • Tip: when rephrasing, try to frame in the affirmative.
  • Syntax: the arrangement of words and phrases to create well-formed sentences.
    • Passive voice: can create impact (in English, the thing at the end of the sentence has the biggest emphasis)
      • But still not generally recommended as more complex, buries the lede, and obfuscates who/what is doing the action. Cool in novels and marketing copy, not in docs.
  • Morphology: the study of the internal structure of words. A morpheme is the smallest distinctive unit of a language having a definite grammatical function.
    • Syncretism: when two different categories look the same. 'The application transferred the data' vs 'the transferred data is in the queue'. 'Transferred' looks the same in both sentences but is actually two different things. Especially important when translating. To disambiguate, consider adding 'that' to the adjective: 'the data that you transferred is in the queue'. Can sound awkward, but consider it for clarity.
    • -ing verbs and gerunds are two different things: 'I am cooking' (-ing verb) vs 'I love cooking' (noun gerund).
  • Summary: what can linguistics teach us?
    • If possible, avoid being vague and ambiguous.
    • Mostly use active voice, but passive voice can help you achieve certain goals.
    • Use 'that' to clarify if something is a verb/adjective or verb/noun.
    • Learn the rules, then learn to break them. The order is important.

Sketchnote by Dennis Dawson:

"A sketchnote: a visual summary of the talk"