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.

No comments:

Post a Comment