Django under the hood: documentation workshop - Mikey Ariel¶

Content strategy¶

Originally it is a marketing term. Which is fine, as documentation is an important part of your project’s marketing!

The core is asking the right questions (even is the answer is simple).

• Who are my readers? Sounds like a simple question. But… are your readers advanced users? Or beginners? Do you need “persona-based” documentation, so documentation for specific groups (“admins”, “developers”, etc)?

• What do my readers want to know? Often your readers need context before they can understand reference documentation. Do you need an end-to-end tutorial? Or just explanations?

  Does the textual content need to be enhanced with video or diagrams, for instance?

• When do my readers need the content? Installation documentation right at the beginning to get started? A reference guide when you’re already working with it? Tutorials for learning it?

  “When” also relates to “when do I need/want to update the documentation?”

• Where do my readers consume the content? Do you need a “man” page? Embedded help in your GUI app? Good, helpful error messages? Online documentation that can be found by google?

• Why do my readers even need this content? Minimize double work. Can you point at another project’s documentation or do you need to describe some feature yourself?

  Similarly, if you need to add documentation to work around bugs or things that don’t work right yet: should you not actually fix the code instead?

DevOps for docs¶

“Content strategy” leverages marketing concepts to make your documentation better. Likewise, “devops for docs” leverages engineering for your documentation.

• Look for a unified toolchain. If possible, use the same tools as the developers of the project you’re documenting (especially if you’re both the developer and the documenter). Git, for instance. Don’t use google docs if the project uses git. By using the same kind of system, everybody can help each other.

• Use out of the box documentation tools like asciidoctor, gitbook, MkDocs, sphinx.

• Use continuous integration! Automatic checker for broken links, perhaps an automatic spell checker, automatic builds (like read the docs does).

  There are automatic checkers like “Hemingway” that can be used as a kind of text unit test.

  You can add custom checks like making sure your project name is always spelled correctly.

• Iterative documentation. Dividing the work into sprints for instance if it is documentation for a big project. Use your issue tracker or trello or something like that to manage it.

Keep in mind: we’re all in this together. Designers, developers, product managers, quality assurance, support engineers, technical writers, users.

Docs or it didn’t happen¶

Some ideas.

• Treat docs as a development requirement. Write it down in your contribution guidelines. Write down what your definition of “documented” is.

• Contribution guidelines are a good idea! They’re an important part of your documentation in itself. Do you want people to help you? Write those guidelines.

  With contrib guidelines you can also steer the direction and the atmosphere of your project. If you suggest that 20% of a participant’s time is spend mentoring new contributors, you send a strong message that you’re a welcoming and helpful community, for instance.

  Also look at non-code areas. Do you want contributions from designers? Do you explicitly like somone to work only on the documentation side of things?

• Provide templates. “If you add a new feature, use this template as a basis.”. “Add a ‘version added’ link to your description.” That kind of helpful suggestions.

• Contributing to documentation is a great (and often reasonably easy) way to get into contributing to a project as a whole.

• Collaboration and training. Sprints and hackfests are great to get people started. There are communities and conferences. “Open help”, “write the docs”. Also mini-conferences inside bigger ones.

Image: my recumbent bike in front of Troisvierges station in the north of Luxemburg, our startpoint this summer for cycling over the former ‘Vennbahn’ railway