November 30, 2010

The Silent Bias

One of the frustrating things about working as a writer in engineering driven organizations is the persistent, although unspoken, bias against documentation. There is a lot of lip service given to how "good documentation is as important as good code", but the truth comes out when the rubber hits the road. Writers as not given the same respect as coders, coding take priority over reviewing, documentation is expected to rush, and documentation is rarely involved in product design except as an after thought.
Not too long ago, I was part of a discussion about how to handle documentation for one of the Apache projects. The community wanted to make it easy for people to submit documentation to the project, so they had set the barrier to entry well below that which was acceptable for code submissions. Before any code written by a coder without commit rights must have the code reviewed by a committer before it can be added to the code base. For documentation the only requirement for making changes was a signed CLA. Everyone agreed that documentation is as important as code, but didn't see how the different standards exposed the truth. Committers didn't want to have to review documentation changes because it was a hit on their time.
The other interesting thing about the discussion was the assumption that writers wouldn't, or couldn't, learn how to use a source control system or a build system. Most writers do find source control systems tedious, but they are also a fact of life for anyone working in engineering centric firms. A writer who is capable of writing good documentation for an open source project is more than capable of learning a build system and a source control system.
I won't go into my other sob stories about how documentation, even documentation that is integrated into a user interface, is treated like an after thought in the product design process. I also won't go into how many writers and writing teams are complicit in continuing the silent bias.
I will say that the silent bias does hurt product quality in the end. Crappy documentation lowers the user's impression of the product.

November 2, 2010

Marking it Up

At my last gig I spent most of my time writing in Frame Maker and Word. It was terrible. These are supposedly the alpha dogs of the computerized word manipulation tools, but they really point out the draw backs to all of the fancy WYSIWYG writing technology that has been developed. The text on the screen looks great, but the interface required to make the text look great gets in the way of writing. All of the buttons and fancy fonts and margin controls and table tools are distractions. The crashes and weird behaviors are annoyances.
When I joined FuseSource I returned to a shop that eschews all the fancy tools for writing in a mark-up language. Most of the documentation is written in DocBook XML. I'm not going to lie and say that DocBook is easy to learn or that it doesn't have it's quirks. You do need to learn which tags to use and when to use them. Some of the tags don't make sense or are overly complicated.
What I will say is that once you learn some of the tags, they fade into the background and you are left with just the writing. Your hands can stay on the keyboard because your not off looking for the bold button or using some key combo. You don't worry about how things will look because it is not in your face. You worry about what the words say when you are writing and wait until you publish to worry about what it looks like.
I've also been doing some work in other mark up languages like Confluence wiki text, Markdown, and Jade. Like DocBook they have their quirks. Unlike DocBook, they are true presentation mark up. The marks do not denote what the word represents it denotes how it will look. This makes the writing process a little different, but using mark up makes creating the content the center of the process. You still aren't confronted with a constant representation of the page. You still don't have to twist your hands into awkward twister poses to underline something.
When you are done creating the content, you can think about how it will be laid out in a medium. You can customize things for professional printing, for PDFs that will be printed out in an office, for a desktop Web browser, and for an iPhone. The layout process has it's own time and space. You can focus on that and not on the words.
Combining the writing process and the layout process is not more efficient. The human mind is lousy at multitasking.