Fog Creek Software
Discussion Board




Learning to Document

There are numerous resources on the web for programming. Whatever the language, someone dedicated a site to it. But what about documentation?

I've been looking for a site (like Joel's) which has more information on how to document. I'm interested in how a good user manual would look like (the "interface" as well as the "data" of the manual) I'd like to know what the options are, and how we could combine various documents (like source documentation, the installation manual, the user guide and the FAQ) into a single database.

In plain English; how do you document, and where did you learn it?

Eddy Vluggen
Tuesday, October 22, 2002

I have a co-worker who believes good user documentation consists of printing out the source.

skipbo
Tuesday, October 22, 2002

Well, it sounds to me like you are really talking about technical writing.  There are websites and newsgroups devoted to this type of work on the web.  Sorry, but I don't have any links for you.  However, I am sure you can find most of these sites through a search engine.  Perhaps, someone else will post a message with some links for you to follow or a recommend a book for you to read?

Charles Kiley
Tuesday, October 22, 2002

http://www.raycomm.com/techwhirl/ is the gold standard.

Joel Spolsky
Tuesday, October 22, 2002

... I should add that I actually learned to document by forcing my self to take some writing-intensive courses in college. One of them had a weekly 3-5 page essay. There are even more writing intensive courses, such as Yale's famous "Daily Themes," which requires 5 essays a day!

Joel Spolsky
Tuesday, October 22, 2002

I recommend Lyn Dupre's book "BUGS in Writing", since it 
deals with technical writing (and, especially, issues concerning
software documentation) in a quite amusing and helpful way.

Roland
Wednesday, October 23, 2002

> In plain English; how do you document, and where did you learn it?

Know why (i.e. in order to perform what task) someone is reading the documentation, and write it to help them do that task. Suit the documentation to the audience as well as the task ... for example a Programmers' API Reference is different from an end-user manual is different from a Planning Guide used by an administrator.

I learned English at school and home, and learned how to document "on the job" (i.e. by being paid to do it, getting instructions from managers, feedback from programmers, etc).

Pay especial attention to "outline" tools ... the list of all section titles (i.e. the table of contents) is the most important aspect of a technical book, IMO.

Christopher Wells
Wednesday, October 23, 2002

*  Recent Topics

*  Fog Creek Home