Writeup of the DjangoCon Europe 2019 talk »Docs or it didn't happen! (with Q&A)« by Mikey Ariel
Mikey Ariel: You might know her as "That Docs Lady", and you're not wrong! Mikey Ariel spent the better part of the last 10 years documenting super-geeky enterprise software, most recently for OpenStack Platform at Red Hat. She is also on the global core team for Write the Docs, Django Girls alumni, co-author of the Happiness Packets project, and documentation coach for open-source projects.
We want to have more users, more contributors, and want to push adoption of our products. We believe that docs can help us, but something is stopping us from working on docs.
A documentarian is someone who cares about documentation and communication in the software industry, regardless of job title. – Says the writethedocs manifesto. Everybody can (and should) care about docs, be they marketing, developers, testers, writers, …
Plan a little, save a lot! Ask the right questions ahead of time.
Why do readers care about the documentation they are reading? Why do they care about the tool they're reading about? People probably do not want to know which button does which thing – instead they want to know how to reach their goals.
This involves differentiating by role – are you talking to users? To administrators? To developers?
Start using architecture charts to differentiate between parts of your architecture, and link to them.
If people are already on your README, they can be assumed to be a different type of person than others, so your README should address that. This one is a good example for an excellent README: Table of contents, welcome note, related work, getting started, link to global and directly helpful documentation, and a community section.
At which point of the usage cycle of the software are users to encounter documentation?
Error messages are a prime candidate – first off, expand your error messages a bit. This will help send people to the right person. Offer a good search, and be ready to help people who are not in the best mood – no frills required.
How much information do you give at each instance of information? Docs? Docstrings? README? Hover texts? Help texts? Documentation that cannot be found does not exist.
In failure cases, try to give as much context and information as possible – provide it beforehand, too, but people will not read it then. Provide direct reasons and alternatives, instead of just sending people to some docs page that will mmmmaybe help them out. Hopefully. Instead, include a description of the action and its context, consequences, and links for further context. Provide alternatives if possible.
Consider these points first. Minutes of consideration might spare you hours of work.
DevOps for Docs
Docs as code:
Documentation lives a good life as a directory in your repo, which improves lifecycle changes that change code plus documentation. On the other hand, if you have multiple repositories that are combined into a single product, you'll be better off to have a separate documentation repository.
Have hierarchical source content – have directories for guides, and keep to short text files. Make users scroll little.
Have a documentation component in your issues/tags/whatever your tool of choice requires. It makes work on documentation more respectable to outside contributors, and less of a second-class citizen when compared with
In Python: Sphinx and Readthedocs. Also MkDocs, Asciidoctor, … There are many low-effort way of doing asynchronous publishing, publishing versioned/release documentation, having previews (netlify).
More than just a spell-checker! Test your documentation in as many ways as you can.
There are tools that check your markdown-embedded code. There are tools like hemingwayapp. There is emender for testing grammar according to your own specification.
Docs or it didn't happen!
Let's help each other as a community to document our code and communities, and keep them up to par. This involves attitudes like "Give me docs, or I will not merge your PR". Document this. Doc the docs.
Follow current projects like the modular docs project. If you're more interested, consider visiting one of the WriteTheDocs conferences – they've been around for some time, and they're steadily growing and expanding to more cities. Be aware of Season of Docs, Google's documentation version of Summer of Code.
What about using pronouns/addressing readers directly? Which is preferable? - MINIMALISM. Use fewer words. Keep it simple. Even more simple than you think. The topics that we write about are so complicated that our language has to be extremely simple. "Property x allows you to do Y" -> "You do X with Y". This is completely appropriate in persona based docs. Address users directly once their role is clear. Give the active voice to humans, things cannot allow you actions, or have attributes. It can include them, or describe them (and have is a dangerous word). Aand you want active voice and no gerounds (and hard to translate).
Collaboration and contributions
How do I find out what to communicate to contributors and documentarians, when I'm not aware of what is important to them. – TALK TO PEOPLE. It's honestly the easiest way to solve this. Ask people with writing experience and ask them to test your software. Offer mentorship to new contributors who can help you fix docs. Facilitate skill-sharing sprints, or meetups, or events, where developers and writers can pair-work on documentation-related tasks.
Ask potential users what their workflows is likely to be (on day 0, 1, 2, …) and port that knowledge to the docs (documenting the UX). Research best practices and templates and look up docs for projects that you like.
Reach out to peers, make yourself available for training and mentorship, and be kind to people who want to contribute. Most writers don't have deeper understanding of how the code is written, but their strategic communication experience is what makes them great writers – respect that!