Information Technology Reference
In-Depth Information
“software documentation is, in practice, poor, incomplete and inconsis-
tent.” To answer this, let us look at the various categories of most product
documentation:
Illuminative
: intra- or inter-development team, engineering design,
production, QA, management reporting
Instructional
: functionality guides, user manuals, administration
guides
Reference
: troubleshooting guides, cheat sheets
Informational
: promotional product announcements, competitive
landscape, cross-industry relationships
Illuminative Documentation
Illuminative documents in different industries use different styles and go
to different levels of detail based on their perceived needs and criticality.
In software, we have industry benchmarks, SEI guidelines, and intra-
organization standards. Dijkstra mentioned the “Separation of Concerns”
in 1974, which had direct applications to documentation. Newer paradigms
like Extreme Programming, Agile methodologies, and even the not very
popular concept of Literate Programming by Knuth are all efforts to make
documentation more formal and consistent. How diligently these norms
and recommendations are followed varies from place to place. Because
these are meant for internal consumption, they are always given a backseat
compared to the other kinds of documents that are inherently more
customer facing.
Such illuminative documents assist in communication between the
business domain experts and the software experts within an organization.
They cover details about all the aspects of the software life cycle in terms
of specific roles and responsibilities of the various groups involved. They
are very important from a software maintainability perspective. It is one
stage of the life cycle (software deployment, or maintenance, or suste-
nance) where developers spend most of their time and resources. One
needs to understand code blocks (especially in OOPS approach), what
worked and what did not work (in migration projects), and why things
were done in a particular way.
Instructional Documents
Instructional documentation, in contrast, has no industry norms and stan-
dards that define it. The content and “size” of the documentation has
changed significantly over the years, and is typically in direct proportion
