“This past week on the WTD Slack forum, there was a bit of discussion around a recent presentation titled ‘Documentation Avoidance for Programmers.’ In the presentation, Peter Hilton lays out a series of tips on how programmers might get out of writing documentation.”
Some of these are funny enough to end up in a Dilbert strip, like saying, “It’s on the wiki” (even when you know it’s not).
And then there are more practical ideas, such as “getting others, namely technical writers to create the documentation.” This is a great idea! Not only do most developers hate writing documentation, but they often aren’t very good at it, since their investment in code does not always translate to good documentation.
Programmers and engineers would usually rather be coding and building things instead of explaining them to others. With documentation, it can take a lot of effort and multiple tries before you get the organization and flow of logic just right and because “experts are hampered by the curse of knowledge. They know too much and can’t identify the assumptions, needed knowledge, and other building blocks of basic that users need.” A good technical writer can develop documentation that is audience specific, including developer documentation.
For a good programmer, writing documentation is a secondary skill at best. More importantly, it is a waste of a good programmer’s time.
The only thing worse than using a developer to write documentation, is using an engineer to write marketing materials. I’m sad to say that this also happens! With a few exceptions, you end up with lesser marketing materials, and have wasted expensive engineering hours to do it. It is better for a seasoned writer to get the engineers input, and then deliver a great product so that the engineer has time to do the same.
