Write the Docs: Alex Gaynor – Documenting Domain Specific Knowledge

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Alex kicked of the set of talks after lunch. He got his start writing software and documentation for the django project. The people who come to django’s docs are of two groups: they’re looking for reference material for a project or are entirely new to django and looking to make a website. The latter group is who Alex focuses on.

In truth the django project has never written down the user profile for those new users. They assume that they know the basics of how the web works. django is a tool within the domain of building web applications; its docs focus on people looking to learn within that domain.

Alex is working on a cryptography program for web developers. He’s found similar tools have very poor documentation and sees the goal of his project as about education as well as development. If you don’t write docs for your world-changing idea you’ll lose.

Can you document around a usability problem? This comes up a lot around legacy software. The conventional answer is no. Alex argues, though, that we can write docs that illustrate how to use a product. What you can’t document around, though, is people’s assumptions. You need to shock them out of their assumed viewpoint. In this sense documentation and design are a partnership. Documentation partners with design to create usability.

If you pick an audience you can write your docs to those personas. It may not be useful for everyone but it will be useful for someone.

Additional reference material must be optional. If it’s necessary to comprehension it must be inline and part of the doc.

The most important thing Alex has tried to do with his project’s docs is to work toward fundamentally having no assumptions. They work to give users the full context of the project and not assume core knowledge.

Your docs should also be prescriptive. You’re the subject matter expert and should make recommendations that your users may not know to make for themselves. Nudge them toward good defaults. Your users may not need to know every single layer of possibility.

One of the most valuable things they’ve done on Alex’s project is to test the documentation with users. They give them the docs and ask that they try to solve a task. They’re not allowed to use Google or other resources, just the docs.

Often users don’t know what they don’t know. Nothing of consequence should depend upon something that your user doesn’t know they don’t know. This can also be where recommendations and nudges come in. It lets users understand what’s going on without necessarily needing to take the action themselves.

Part of asking for feedback on documents should be about giving those users the means of contributing that feedback. Let them help improve your project if they have ideas for doing so.

Something else to realize is that your users don’t care about your domain as much as you do. They may never say thank you, and that’s okay. To a user your domain of knowledge is the impediment to them getting their job done.