TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
