UTOSC 2008/How to write good HOWTOs for open source projects
This presentation will be from the point of an English major.
The broader the user base that you want to use your product, the broader your documentation needs to be. Don't expect novices to even touch a project without documentation.
Keep audience in mind. Writing for admins is easy because they use the same vernacular (The language of a people, a national language or the langauge unique to a particular group of people; jargon, argot, slang).
People usually turn to documentation when they are stumped.
Create a style guide. Consistency is more important then following grammar and syntax rules.
Just get to the point. Be concise. Poetry is the best example of writing concisely.
Take the time to revise the text. Revising is the craft part, the discipline part.
When you think and edited copy is complete, read it aloud. Hearing the text will greatly help catch issues.
Avoid multiple prepositional phrases. ie "in the data center on the left side, of the street, under the dome, .... is some cool hardware." Either trim the fat, or move the location description to another sentence, so that a reader can skip over it if they feel it is unimportant.
Test the test on real users. Have beta test readers perform some of the functions in the documentation to see if they make sense.
Keep text updated and current. Schedule audits, perhaps quarterly. With every revision, review documentation.
Documentation types:
- man pages - good for admins and command option reference
- howtos - easy reference
- help pages on web - can include images, best for novices
- wikis - flexible format, allows for multiple contributors
- faqs - easy to maintain, handy for troubleshooting
- books - hard to publish, impossible to keep current, good for portability