Ideas and Takeaways from Write the Docs 2018

My notes from the talks at "Write the Docs" 2018 in Prague

documentation / technical writing / conference

Here are my notes from some of the talks I attended.

Don’t say “simply” - Jim Fisher

I already look out for the words “Just”, “simply”, “obviously” and “naturally” in my speech patterns and try to avoid them. In this presentation Jim Fisher took an in-depth look at the word “simply”.

From another presentation, “Simple made easy”, Fisher got the distinction between “simple” and “easy”. Simple refers to concepts and is objective. Easy refers to actions and is subjective - what’s easy to some people is not easy at all for others. In our everyday speech, we often confuse simple and easy because we forget that behind the easy-to-follow instructions are hard-to-grasp concepts.

Like its cousin “just”, the word “simply” makes people frustrated and ashamed when they can’t understand or follow the instructions.

Fisher recommends to remove “simply” from your texts and use one of the alternatives:

  • Admit that the undyling concepts might be complex.
  • Be more specific why you think something is simple. The best way to do that is to give absolutes: “This library is very small”, “You will type three commands”, “You will have a working installation in 10 minutes.”
  • Show, don’t tell: “These are the required lines of code”
  • Don’t replace “simple” with anything, sometimes “simple” is a filler word.

Fisher found over 92 millon instances of the word “simply” on GitHub and wrote a script to help authors to remove this word from their code. While he made pull requests to repos, he discovered that some people like the word and jokingly admitted that he fell into his own trap by saying “Simply don’t say simply.”

A11y-Friendly Documentation - Carolyn Stransky

This talk was a reminder that documentation should be as accessible as web applications. Some people use screen readers, some need larger font sizes, need good contrast or who need special assistive devices to use a computer. One out of every 200 developers is blind or hard of sight.

Concrete tips for documentation:

  • Pay attention to the structure and hierarchy of your document. Use semantic HTML for headers, lists and emphasis. Use <nav> and <aside> to mark content that is not part of the main text flow.
  • Subheadings and small chunks help everyone to grasp what the document is about.
  • Turn off CSS to see the order of the elements on the site elements.
  • Check if you can press tab to navigate through the page without getting lost
  • Do all focusable elements have visible focus state?
  • Do you have links to skip navigation?
  • Do all images have alt attributes or a textual description near them? If the images are purely decorative, add an empty alt attribute or the role="presentation" attribute. If you leave out the alt tag for decorative images, the screen reader will read out the (sometimes cryptic) image name.
  • Use <code> tag for code examples, not images. Use meaningful variable names, watch out for trailing extra spaces, because screen readers will read them out.

Tools for checking the accessibility:

The talk ended with the section “This is for everyone” from the Government Design Principles of the United Kingdom:

Accessible design is good design. Everything we build should be as inclusive, legible and readable as possible. If we have to sacrifice elegance - so be it. We’re building for needs, not audiences. We’re designing for the whole country, not just the ones who are used to using the web. The people who most need our services are often the people who find them hardest to use. Let’s think about those people from the start.

Run your docs - Predrag Mandic

If you have a highly configurable software with a complex, multi-step, multi-component setup, you need to document every detail of the installation process. But in some cases you don’t need all the complex setup, it would be fine to go with all the documented defaults: Developer installations, acceptance tests in the continuous integration (CI) system, proof-of-concepts, customer demos, etc. You could automate these installations with a script, but that would mean duplicating “code” between the installation instructions and the deploy code. To avoid that duplication, you take a lesson from Literate Programming and create a script that extracts the installation instructions in your documentation and runs them.

To write such a script, you need metadata: Which code examples are installation instructions and which are not, different instructions for different cases. One way to encode the necessary metadata is the info string of fenced code blocks in Markdown. The first word of the info string is always the highlight language. The Markdown processor ignores all other words in the info string, but the script could parse them. Example:

```bash install_type=default
sudo apt update
```

This approach also has the benefit that you can test your installation instructions as a part of your continuous integration and make sure your documentation is correct.

Learning to love release notes - Anne Edwards

Release notes contain information about bug fixes, new features and behavior or API changes. Anne Edwards gave us lots of tips on how to improve the usefulness of release notes:

  • Have a clear image of who the readers are. What situation are they in, what knowledge do they have? What information do they need from the release notes?
  • Use “you” instead of abstract persons or systems. Don’t be too formal or impersonal.
  • Don’t be too technical
  • Provide context
  • Don’t try to be too funny or whimsical, like some release notes in app stores. The humor might not translate across cultures and might hide the information.
  • Don’t introduce each bug fix with “Fixed …”
  • Be accurate, clear and concise (in that order).
  • Re-write the message to improve it. First expand the text to contain all the information and its context, then simplify.
  • Imagine you’re talking to someone
  • Use a sentence template like
    • You can now …
    • X no longer does Y when Z
    • X no longer does Y. This means you no longer need to do Z.

This talk made me aware that the rules for well-written commit messages are different from what release notes should convey. The different text types have different target audiences and different information needs. The commit messages are helpful for the author of the release notes, but are not a substitute:

  • The subject line of a commit message is too short and too action-oriented to be useful as a release-note description.
  • The body of the commit message may contain technical details and in-depth context explanations that are not relevant for the reader of the release notes who asks “What do I need to do differently now?”
  • Depending on the workflow of the team and the “commit discipline”, the release notes might contain “internal” fixes (for code style, refactoring, etc) that are irrelevant for release notes.

On the topic of release notes I re-read the “Keep a change log” site. Before this talk I associated release notes with CHANGELOG files, but now I see that typical CHANGELOGs have a slightly different structure, with sections labeled “Fixed”, “Added”, etc. Change logs seem to be a kind of middle ground between release notes and commit messages. For the development teams which have a good merge/commit discipline and hate writing change logs, I discovered a convention and command line tool to do what you should do: Generate the change log from commit messages.

Conclusion

When I attended Write the Docs in Prague in 2016 I totally loved it because of the friendly, welcoming atmosphere, reminding me of SoCraTes. It felt kind of “cozy”. I met some interesting people and everyone was very approachable. This time I had a hard time talking to anyone between the talks because everyone gathered in the main hall, which became a cacophony of voices - an introvert’s nightmare. But apart from the crowdedness I can recommend the conference for many people interested in writing - technical writers, documentarians, testers, community managers and developers.

Badge Flair
For the badge decoration contest I went with a “Friendly Monsters and Robots” theme.

If you want to see all the talks, have a look at the “Videos” page of the conference web site.