Documentation: It's Important and Difficult
Nigel Babu (~nigelb) |
6
Description:
One of the ways that we encourage non-coders to contribute to Open Source projects is by writing documentation. And sometimes, as developers, we tend to look down on writing documentation. Personally, I think it's one of the most critical part of a project. If the documentation is hard to sort through or hard to read, there's going to be a whole bunch of frustrated users and contributors.
How can you write good documentation? Last July, I attended an unconference called "Write the Docs" in Berlin and we had an open discussion about how to create an environment for building good documentation. In this talk, I'm hoping to present some of the rules that we came up with during those conversations and also talk about what we did in the CKAN project to make our documentation far better than it used to be.
Summary of Rules
- Pick one markup style and run with it, authoring tool does not matter.
- Pick a toolchain that leads from input -> final docs consistently.
- Always produce final docs in the formats your users require.
- Define a style guide for your documentation and enforce it.
- Always have translations in mind: if you don't have translations now, you will do later.
- Base translations off one, agreed, master set of documents.
- Language-specifc style guides.
- Have a documented process for reacting/interacting with the developers. (e.g. new features must be documented before acceptance)
- Have a documentation-specific element to the overall release cycle (inc. deciding if documentation is allowed to block releases)
- Have a QA process for documentation.
- Have rules about updating and archival of documentation (e.g. continually update document the software while the software has not reached EOL)
- Documentation must have a feedback mechanism.
Prerequisites:
Interest in documentation.
Speaker Info:
Nigel is a web developer and sysadmin based in Delhi, India. He loves building web applications in Python. He works as a consultant Sysadmin and Python Developer during the day. In his free time, he contributes to Mozilla.