Conference Report: 2000 LISA: Why the Documentation Sucks, And What You Can Do About It

Steven Levine spoke and sang about documentation. Steven is a technical writer with SGI and talked about four major subjects: myths, difficulties, projects, and improvements.

First, Steven talked about some myths. One myth is that writers are editors. In reality, writers not only edit stuff others (such as developers) write, but write their own original content, maintain other existing documents, and produce both hardcopy and online help and web-based documentation. They also coordinate and organize and are detectives; they have multiple information sources and work between different groups or departments. They are also responsible for documentation consistency and legal issues.

He then discussed some of the difficulties that writers face. He started this section with a song, and yes, all 300-plus audience members were singing along with the chorus. The major difficulties are lack of resources, conflicting perspectives, no usability (if any!) testing of the documentation, shorter release cycles, distinctions in hardware and software, the problems of writing from experience on as-yet-nonexistent products, and having to rely on developers' time and interest to improve the documentation.

Third, he discussed some of the typical projects that writers are involved in. Not only are they responsible for administrative documentation but also online documents, procedures and examples, and man pages (which may not be sexy but are certainly very useful).

Fourth, Steven discussed how to improve the documentation. The short answer is it's a two-way street. If you see something needing work in a document, let the author know. There's always some form of contact information (even if it's postal mail). Document what you want solved. Document what you did to work around a problem to help others not have to go through it themselves. Formalize your informal people networks; if you're a developer, take your writer to lunch. Produce libraries of examples, procedures, tricks you use, and so on. Collaborate within the company across department lines. Collaborate with friends and aquaintances at other companies.

Back to my conference reports page

Back to my professional organizations page

Back to my work page

Back to my home page