Information Technology Reference
In-Depth Information
Documentation for these purposes is likely to be written to the same guidelines as
that used for specifications and so on. I've noted it here because it is an aspect of
documentation that is sometimes overlooked, in particular the fact that it may need
to explain
why
as well as
what
.
Technical Reports
Another common form of professional writing is the broad category of document
that can be described as a technical report. In principle, everything from a research
paper to code documentation might be in this category, but I'm using the term in
a narrower sense: a report concerning some technique or technology. The reader of
such a report might in some circumstances be another computer scientist or software
engineer, but might in other circumstances be a manager, assistant, funder, lawyer,
accountant, consumer, or client—that is, just about anybody. Thus a key difference
between a research paper and a technical report, as I am using the term, is that the
audience may be inexpert or uninformed about the field.
Perhaps the best way to explain is with an example. For instance, a technical report
could concern the outcome or progress of an investigation, such as a report on the
reasoning and arguments underlying the engineering decisions in a major software
development. In circumstances where large developments can easily cost millions—
and sometimes cost billions—management, investors, and other stakeholders expect
that fundamental decisions will be given careful attention, and defensible processes
may require that they be thoroughly documented.
A technical report of this kind might include:
Examination of choices and options.
For example, the authormight examine ques-
tions such as: What data structure to use? What criteria to apply? Which tools are
appropriate? Should software be bought or written? Should it be open source or
proprietary? If the former, what is the proposed support model, and what is the
evidence that it will work?
Evidence of due consideration.
What resources were used as input to these deci-
sions? Or, alternatively, what resources are required to make these decisions, and
what will they cost? What are the possible costs of
not
undertaking due diligence
for these decisions?
Evidence that claims correspond to facts.
What tests were used to validate manu-
facturer's claims about their products? Or what tests might be used, and why are
they appropriate?
A technical report can be used to both record the work that was undertaken to make
the decisions, and to summarise them for a non-technical audience.
There are many other reasons why a professional might need write a technical
report. They can, for example, be used to examine questions such as: Should a project
be undertaken? Why did the project fail? Should the current project be cancelled? Is
