How to Write Really Good Documentation

Write a really bad manual and you’ll not only lose users, you’ll create ex-users who go out of their way to tell others how bad your application is. Documentation matters.

Forte, Brian. Red Hat Magazine (2007). Articles>Documentation>Writing>Technical Writing

How to Write Really Good Documentation: Donald Knuth Was Wrong

In the continuing absence of maturity in the software world, it’s the documentation that has to treat the tool-user with respect. Which is a further argument against Knuth’s Literate Programming. Since it’s all too common to see software toolmakers treat tool-users with short shrift, it’s a useful caution to have the ’software is written in one corner and documented in another’.

Forte, Brian. Red Hat Magazine (2007). Articles>Documentation>Writing>Technical Writing

How to Write Really Good Documentation: Four Rules and an Axiom

Keeping to the four rules articulated here—and never forgetting the axiom—will definitely improve your documentation. If nothing else, recognizing and observing these rules will raise the status of documentation and the people producing it. And they’ll use that raised status in at least two ways.

Forte, Brian. Red Hat Magazine (2007). Articles>Documentation>Writing>Technical Writing

Semi-Definite Rules for the Indefinite Article

Technical writing–perhaps more than any other sort of writing–gets read and used by people from every corner of the Anglophonic world. And people don’t get less sensitive to perceived slights or the appearance of cultural insensitivity because it’s a manual or help page. If anything, they’re more sensitive in such a circumstance.

Forte, Brian. Red Hat Magazine (2007). Articles>Writing>Technical Writing>Grammar