Information Technology Reference
In-Depth Information
Grant applications, funding proposals, and funding requests.
Requests for or responses to tenders.
Technical documentation: for example, designs, specifications, test specifications,
code documentation, and handover and support documentation.
Non-technical documentation: for example, requirements, project scope descrip-
tions, project overviews, management documentation, risk documentation, accep-
tance records, and manuals.
Requests for comments.
Technical reports, including reports to management, incident reports, and papers
recommending or assessing technical decisions.
Plans, goals, and strategies.
Patent applications, expert reports for legal proceedings, and other forms of legal
document.
Popular science articles.
This list consists, more or less, of work that could be regarded as undertaken in an
expert capacity. The link between the items above is the concept of
professional-
ism
. While some documents may be intended for only a tiny audience, there is an
expectation that a professional communication be balanced and objective.
Another aspect of the task is the mode of delivery. The document might be brief or
long; delivered in person, or in writing only; available to a wide audience, or to just a
few key recipients; require reflection and consideration, or require a quick response;
be permanently available on the Web, or distributed to a defined group. There are
many such variations, and all of them should influence your decisions as to the form
of the document and how you will go about writing it.
Documentation
The topic of how to produce code and project documentation is explored in detail
in a typical computer science degree. Elements include requirements, specifications,
designs, test plans, manuals, and so on, both embedded in the code and as sepa-
rate documents. Workplaces and projects usually have defined standards for these
materials, and there are excellent texts on how to create them.
However, most computing professionals document much more than the software
they develop. For example, some documentation tasks don't concern software under
development, but instead concern software and hardware used by the development
team. Consider overviews and handovers given to new employees. What information
should, say, a new employee be given about the working environment? What should
a departing employee be asked to record? Documentation might concern:
Systems, installations, and hardware.
Coding standards and workplace facilities.
Algorithms and packages—not just what they are, but why they were chosen and
what alternatives were considered.
Online resources that can be used to guide decision-making.
