Pages that host discussion of various aspects of technical writing. I occasionally write documents that live in the documentation section.
Like "technical debt," or the realized costs of defered development and refactoring, documentation projects risk a similar information debt which has critical implications for the way that we write, organize, and maintain documentation.
"How to Teach People to Program," outlines some of the problems with the ways that we teach people to program, and the flaws with the current literature and approaches to this kind of technical material. This page is part of a collection of pages on technical-literacy.
"Why the documentation sucks," outlines a few ways that documentation (often) sucks and provides an overview of some best practices that we can use to make documentation ?suck less.
The skill of technical writers and a thought on automating documentation. Is it possible to automate the process of generating documentation? Can developers "own" documentation projects?
Atomic Documentation. Documentation should be written in very small units that are self sufficient, and address very small and specific topics, questions, and features. The system which builds and displays documentation should then be able to either usefully present these "atomic" units or stitch more complete documentation together from these units. This makes documentation easier to maintain, and arguably makes documentation more valuable for users.
Compiled Documentation The "end-product" Documentation should be statically compiled, unlike (most) web-based content that is dynamically generated. This allows writers and teams to verify the quality of the text prior to publication, and allows the "build system" to automate various quality control tests. Documentation is particularly suited to this kind of display generation because it changes very irregularly (no more than a few times a day, and often much much less often.)
Pipes and Filters The process of publication can--like code--is basically passing text (and examples) through various levels of processing until the arriving at a "final product."
dexy is a document processing and authoring tool for "literate documentation."
posts is a collection of all rhizome posts tagged tagged with "technical writing".
tychoish technical writing is an old archives page, written to collect some of my early posts on the subject of technical writing.
resources is a collection of external links on technical writing related topics.