The problem with The Month Where Everyone Focuses on Improving Documentation is that most people are terrible technical writers
Why not have a month where everybody focuses on improving documentation like that month a few years ago where everybody focused on security?
Well, part of it is that most people suck at technical writing. The technical part, maybe, but the writing almost definitely not. Writing is hard (as I’ve learned firsthand), and technical writing is a special genre of writing that requires a comparatively rare skill set, combining technical background with strong writing skills. Because it doesn’t matter how much technical information you know if you are unable to convey this information to anyone else clearly.
Also, there are lots of tools available for identifying potential security problems. PREfast, for example, can alert you to potential buffer overruns, and other scripts can hunt down uses of deprecated functions and similar potential security problems. On the other hand, how do you write a script that locates bad documentation?
Pre-emptive snarky comment: “Just write a script that jumps to a random MSDN page!”
What’s more, technical people tend to write documentation for other technical people, on the assumption that the reader is already familiar with the material. Even knowing how to recognize that something “obvious” may not be obvious to everyone is a skill that takes time to develop. And as I have learned over and over again, it’s a skill that I myself do not possess. Consider, for example, my posting that merely restates what I thought was obvious from the documentation.
There’s another problem with taking everybody on the team off their normal tasks and focusing them on documentation: How do you explain the one month delay in the product? Even the one-month delay for the so-called security push had its skeptics. Imagine if you told everybody that the product was late because we pulled the development team off of fixing bugs and told them to write documentation.
Light
Dark
0 comments