This is a read only archive of pad.okfn.org. See the
shutdown announcement
for details.
writethedocs-communityrules
- 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)
--> React early, react often.
- 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.