PoorDocumentationSkills

The folk with the skills to do the work aren't those with the skills to write it up

Description

The folk with the skills to do the work aren't those with the skills to write it up.  In general, someone with technical skills will want to use these skills to perform technical work rather than writing documentation. 

Discussion

In general, someone with technical skills will want to use these skills to perform technical work rather than writing documentation.  They will want to learn technical skills in preference to writing skills.  This is probably more of a problem in traditional environments than in modern, where documentation needs are reduced and also where communication is a valued and respected skill.  Yet still ‘techies’ dislike documenting their work.

Prevention, Amelioration, Cure

Traditional

Employ a MercenaryAnalyst to do the documentation.  This is a variant of the technical writer where the writer can understand the subject matter by inspection, with only a small amount of aid from the producer of the product being documented.  Ensure you are doing the documentation for valid reasons; see Ref 1.

Modern

Modern Agile approaches demand less documentation during development, aim at SimpleDesign, and attempt, as one of the principles of ConstantRefactoring, to write self-documenting code.  Yet documentation may still be required.  Whether this is done by the developers or by specializing technical writers, the process should benefit from the habits of increased levels of communication inherent in agile approaches.

References

1. Agile Documentation – Essay by Scott Ambler on good and bad reasons for documentation, and related topics.