Write the Docs Prague 2021

Published: Last updated:

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:

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:

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:

To address this:

Two approaches in a new industry like crypto:

  1. Invent new terminology: how does this map to existing context, such as fitting crypto into current financial regulatory frameworks?
  2. Repurpose existing terminology: important to have a glossary to disambiguate overloaded terms.

Two principles:

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?

Improving docs culture:

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.

Random things I learned