Re: IT documentation

["Mark Baker" <listsub -at- analecta -dot- com>]

Stitzel, Ken writes:

> Two interesting pointers about an IT manager's view of documentation. This
> might ruffle a few feathers, although buried deep in the agilemodeling
> treatise is a positive comment about the value of hiring real tech
writers:
>
> http://www.infoworld.com/article/04/02/27/09OPconnection_1.html
>
>
http://www.agilemodeling.com/essays/agileDocumentation.htm#StrategiesForAgil
> eDocumentation

It is important to notice that both these essays are concerned with system
documentation as opposed to end user documentation. The audiences for the
documentation they are describing are programmers and IT staffers, not end
users.

Here is the sort of issue that can arise regarding system documentation.
Given a complex piece of code that will be difficult for a maintenance
programmer to understand and change, how should the current programmer best
spend his time?

a) Thoroughly document the function
b) Refactor the code so that it is less complex and easier to understand

Agile programming says the b is preferable to a. However, this has nothing
to do with what documentation is required for end users.

Technical writers can be involved creating system documentation as well as
end user documentation, but it is important not to read comments on
documentation from the agile programming community as applying to end user
documentation. They are usually talking about system documentation.

---
Mark Baker
Analecta Communications