Write the Docs Prague 2021
This year's "Prague" edition of Write the Docs was another virtual conference, run on Hopin.
The following notes are incomplete: I didn't attend every talk, and didn't take detailed notes on every one I attended. So these notes are just the key bits of info I wanted to save.
Writing day
This is Write the Docs' equivalent of sprint days at open source conferences: a chance for people to contribute to projects, work with other documentarians, and learn. I spent the morning exploring Obsidian Publish with Ursula Kallio, which may have been slightly off topic (we didn't do any writing!), but was fun. I was glad to find a way to take part that didn't involve writing: after writing all week, I wasn't particularly excited about more writing - but the chance to hang out and informally learn with another tech writer was good.
Talk highlights
These are notes from some of my favourite talks - information I want to keep for future reference.
Hitchhiker's Guide to Documentation Tools and Processes - Lukas Reußner
Talks description - Sketchnotes by Linette
A great breakdown of the requirement categories to consider when choosing your documentation tooling, and the general tool categories out there. Lukas then mapped the two sets of categories to each other, using the Quality Function Deployment (QFD) Method.
He provides a detailed set of example spreadsheets for using QFD to choose docs tooling.
Comment: This was a brilliant talk to kick off the conference: an overview of tooling and requirements. I loved the use of QR codes on the slides to provide links to resources, and the process-geekery of taking an engineering requirements tool (QFD) and reworking it for use with documentation tool requirement gathering.
When documenting is designing: How to assist API design as a technical writer - Fabrizio Ferri-Benedetti
Talk description - Sketch notes by Linette
The core assumption of this talk is that writers can improve anything made of words, and this definitely applies to APIs:
- API designs are words - endpoint names, descriptions, error messages and so on.
- APIs enable conversations.
- API description formats / API specs enable API-first design, which is a word-filled process.
- There is a lot of overlap between API designers and tech writers:
It's in the interests of the tech writer to get involved in design. Badly designed APIs are harder to document!
How to help with API design, while keeping design a shared/team concern:
- Advocate for API first design. Devs may prefer to start coding. Show the workflows and the value they give.
- Push for API design guidelines.
- Create an API style guide for the docs bits within the spec file.
- At minimum, own summaries and descriptions.
- Provide naming expertise.
- Join or set up API design reviews.
- Fight for meaningful error messages.
- Build an internal API viewer. This can be a prelude to the client-facing dev portal. It allows everyone on the team to view designs in progress.
Comment: This was a talk close to my heart. I've recently worked on a large API docs project, and would love to do more API-related projects, including design and developer experience work.
Cognitive Ergonomics in Technical Writing: Lessons from the Field - Anita Diamond
Talk description - Sketchnotes by Linette
The problem of specialist terminology:
- Our brains learn new words by gauging context and creating a mental model of the new word through association with familiar words. Too many new words become impossible to decipher.
- Our immersion in a subject area can blind us to how inaccessible its language is.
To address this:
- Categories: locate specialist terms within familiar categories.
- Provide additional cues: diagrams add another means of perception, another context for readers.
Two approaches in a new industry like crypto:
- Invent new terminology: how does this map to existing context, such as fitting crypto into current financial regulatory frameworks?
- Repurpose existing terminology: important to have a glossary to disambiguate overloaded terms.
Two principles:
- Provide the least information required by a specific audience to perform a specific task.
- Provide the right information in the right place at the right time.
System 1 vs System 2 thinking: system 1 widely used, intuitive, leads to errors and bias. System 2 used as little as possible, slower, rational, required effort and working memory. When guiding users through complex or important processes, we need to encourage system 2 thinking.
Think about information experience: user journeys, usability of information, content that supports cognitive ease, multiple media. Work with UI design if possible. Technical writing is UX.
What is a great docs culture?
- Active collaboration and knowledge sharing across disciplines.
- Awareness of the whole docs lifecycle.
- Measure docs impact.
- Great internal documentation.
Improving docs culture:
- People often have mistaken preconceptions about tech writing:
- Define a docs process and educate coworkers about the process and value of good writing.
- Docs can be an afterthought at the end of a sprint:
- Be involved at the beginning of the project to ensure completeness and quality.
- Seek sponsors: senior people in the org/team to embed you in the process.
- Devise success metrics.
- There can be too much docs work for one person:
- Empower people with skills to contribute to docs (style guide, workshops, templates)
- Create doc systems that work with existing behaviours so people can easily contribute.
- Avoid documenting without a clear purpose:
- Request user stories or similar evidence (support tickets, user feedback, client requests)
Comment: The growing focus on psychology is a noticeable trend of this conference (and last year's) People drawing on their psychology background in one way or another to make themselves a better tech writer and improve user experience with docs.