Just a Gwai Lo - fun within prescribed limits

My worries about Eric Shepherd's presentation being too focused on developer documentation were both correct and unfounded. Correct because he only talked about developer documentation for the Mozilla Corporation. Unfounded because everything he talked about applied directly to end-user documentation writing. Some notes here, then a paraphrase of my comment-slash-question at the end. He broke the talk into sections:

• planning and organizing
• the five C's of documentation
• creating documentation
• who decides who writes
• gathering information
• some do's and don'ts

He showed a continuum of openness, from less to more open: published documentation (without comments), commented documentation, and collaborative. The distribution of documentation also proceeding on a continuum from less to more distributable: printed, downloadable, and browseable. He also talked about the advantages of using wikis—anybody can contribute and correct, they take advantage of everybody's strengths, and even non-technical people can contribute—and their disadvantages (prone to sabotage, clueless-if-well-meaning people, and potential for spaghetti documentation. Mmm, spaghetti documentation.

The five C's of documentation that Eric listed are:

• completeness, meaning cover all topics and make the documentation as thorough as possible, but not too thorough.
• correctness, with testing of sample code (or, in my case, the instructions I write out for people)
• clarity, meaning formatting and writing in easy-to-understand language designed for readability.
• convenience, meaning organize the documentation so that the solution is easy to find.
• consistency in language, spelling, grammer, colours and formatting

Creating documentation means making tough choices, depending on the time a writer has to write the documentation but also how soon to revisit. He recommended finding ways to remember and remind to revisit documentation as new releases of software come out. As to who writes the documentation, since he discussed developer-focussed documentation, he listed developers, writers, managers and readers. No mention—at least to my recollection—about users, but maybe readers encompasses that groups. He touched on documentation requiring maintenance (everything requires maintenance) by monitoring changes both in the software and the documentation itself and monitor its organization. Also he listed some tools (wiki discussion pages, IRC, email and instant messaging) used to communicate between programmers and documentation writers, and, by extension, users.

An interesting section of the presentation focused on information gathering. He listed reading design notes, discussion archives, source code and asking the programmers themselves, but I wondered about casting the net wider, like asking the community as well as the users. I sometimes come across something that I know—or think—is possible and want to document, and I know if I ask on the support forums I'll get an answer, but as a documentation writer, I'm afraid of looking like it's something I should already know. It's something to get over, since at the end of the presentation he gave some advice to documentation writers which included "check your ego at the door" and "don't be territorial" and "collaborating means admitting that someone knows more than you." That last one is the answer to my worries, and I'm going to make an effort to ask the community if something is possible and how, and if appropriate or necessary, elaborate on the answer in a step-by-step way.