Training, Teaching and Learning Materials Development

LO 2: Design documentation
Information Sheet 1 Technical documentation basics
Figure 1 below helps map the process of creating technical documentation, where requirements and standards
are on an equal level as starting points in the process.

Figure 1: The place of requirements gathering in creating technical documentation

Before gathering and validating requirements for any particular documentation to be created or reviewed, it
helps to understand some basic requirements as they apply in general and to all forms of technical
documents.

The importance of documentation

There are many ways by which the importance and purpose of documentation might be neglected. The
experience of increasing paperwork and computerised work flow systems, added to email, internet, intranet
and the range of forums in organisations, can altogether lead to a feeling of information overload. At such

Learning guide 32 Date 08-2017 Page 1 of 9

Author: IT Experts
 Training, Teaching and Learning Materials Development

times documents can easily be overlooked and lost. The idea of working on documentation may have less
appeal than working on a computer desktop.
Yet any sense of dread and futility related to documentation is misplaced. Documentation is crucial in many
respects. Collectively, it is the means by which an organisation systematically understands itself and its
purpose, to then develop and grow. In the IT industry, fulsome documentation is also a basic requirement for
finished work to meet client needs.
In the information age businesses are built on platforms that process, capture and disseminate information,
and that platform is supported in all its parts by a range of technical documentation.

Basics of form and function

A technical document may be a form, report, product specifications, records, engineer’s test results,
benchmark details, an operating manual, photograph, a schematic diagram, or minutes of a meeting.
A technical document can also exist in any media. For instance, details about a network configuration can be
stored on paper, CD, word processing file, as code, in a database or through intranet files on the web.
Managers, technical staff and operators all use documentation. Technical and operating manuals are highly
visible examples of the documentation that is typically produced by a project, such as the installation of a
local area network, as an example. The audience for such technical documentation would be IT specialists
who develop and maintain software and hardware, and the documents would include text and diagrams about
the system, including software and hardware.
Technical documentation must be accurate, complete, and accessible. Complete illustrations, facts, figures,
numbers and conventions that support and inform the people who will use the documentation must all be
considered when planning documents.

A broad view of requirements

To incorporate all those elements and know what exactly is needed demands a good understanding of the
purpose and audience for a document. This understanding may be due to the composer being an expert in that
area. To cite our example above, you may have worked on the LAN from design through to implementation
and staff training. You will then probably need someone to review that document to ensure its technical
accuracy, and ideally a third ‘pair of eyes’ to correct any mistakes and ensure that it clearly expressed and
accessible to most readers.
If you are to create technical documentation outside your knowledge or skill area, you will need the advice,
input and reviews from technical experts within the organisation or reliable advisors from outside. Both
examples can require a detailed understanding of businesses, technical, operational and information needs,
which is gained by a process of collecting and analysing requirements.
Requirements begin with an understanding the goals of the organisation. This is then followed by the goals
of stakeholders in a particular product or project or area, such as users, customers, suppliers or policy-
makers.

Document management and version control

In some organisations, vital information is trapped in piles of paper, locked in filing cabinets or scattered
among incompatible files. In others, the content is stored on servers, laptop computers and CDs or DVDs.

Learning guide 32 Date 08-2017 Page 2 of 9

Author: IT Experts
 Training, Teaching and Learning Materials Development

Understanding the policies, procedures and methods for document control that exist in an organisation is an
important part of requirements specification. This understanding is also a precondition for the later design,
review and production of documents. If requirement specifications also encompass a system of
documentation, then the specifications may include the ways and means used to manage documents and
version control.
Manual or informal systems for recording data and records can create confusion, mistakes and delays, as
technical workers waste time searching for the information they need, or recreating data that already exists.
The key point is that information in a document, regardless of its format or media, should be well managed.

The basic methods of document control

The simplest form of document control, especially with single sheet documents and diagrams, is a small
diagram for inclusion with all technical documents. Saving the diagram as a template enables its inclusion,
with details, on all procedures and instructions, for instance.
An organisation may have a range of information that should also be recorded. A control table can be
included at the front of longer documents, or with the master copy file, as shown in Table 1.

Table 1: Version control table

Date Produced by Reviewer Editor Version

25/07/07 John Smith 0.1

21/08/07 Jane Gray 0.1.1
28/08/07 Vince Price 0.1.2

Configuration management
Depending on the medium, an organisation’s policies for storage of documents will discuss where
documentation is to be kept and how it is to be accessed. That documentation may be paper-based, on a
server somewhere or backed up onto a CD. It is important the procedures for the storage are created and
adhered to, and these too may be a precondition or a part of requirements specification.
Configuration management refers to the storage and security of documents. Table 2 below is an example of
configuration management.

Table 2: Configuration management example

Item Location Responsibility

Draft
(destroy when master copy is available)
Master copy
Baseline digital copy
Hard copy master

Baseline control, as shown in a template in Table 3, refers to the minimum level of support and control for
documents. Again, templates help ensure that this level of information is on all documentation.

Learning guide 32 Date 08-2017 Page 3 of 9

Author: IT Experts
 Training, Teaching and Learning Materials Development

Table 3: Baseline control

Name Signature Date

Author
Project manager
Reviewer

Defining the scope of work

Understanding the scope of technical documentation requires answers to the following questions:
 What is the goal of documentation (in a clear and refined description)?
 What is to be achieved by technical documents?
 How is it to be achieved?
 Who would normally achieve it?
 What other resources will be needed to achieve the goal?
When you have the answer, you have a much clearer picture of what the documentation is all about. In
defining the scope of the job of creating or reviewing documents, you would:
 Arrange meetings with the sponsor and all stakeholders to determine their requirements.
 Clearly define the goal and objectives for the project of creating documentation, based on the needs
and expectations that you determined.

Working out what is required

From broad questions to details
To start gathering requirements you first need to ask broad questions:
 Why does the organisation need a particular document or a system for documentation?
 What exactly is missing, or not working?
 Is there a problem with the content of documents, their format, or their availability?
 What will they use the information in the documents for?
You will also need to consider the needs that might arise as one system connects to other systems. Is there a
technical problem, a service problem or a support problem? Is the documentation compatible with
organisation rules, and goals and policies? Is a change to documentation needed because of government laws,
or because the needs of clients aren’t being served.

Learning guide 32 Date 08-2017 Page 4 of 9

Author: IT Experts
 Training, Teaching and Learning Materials Development

Gathering details of different, sometimes conflicting needs involves forming a clear understanding of
relationships between goals (the different reasons why), functions (what for) and constraints (limits of scope
and budget etc). You will need to understand system behaviour, how communications are organised, the
information technology, and definitions of acceptable service.
You can now begin to work out what technical documentation is required by an organisation by asking:
 What documents does the organisation need?
 Why doesn’t it have them already?
 What documents exist that aren’t necessary?
 What are the documents used for and by whom?
 What information should they include?
 What format will they have? What style will be used?
 Where is the information collected, where does it go?
 How are the documents stored?
 What will happen if you don’t have them, or they aren’t reliable?
Table 4 outlines and comments on types of requirements for technical documentation.

e 4: Categories of requirements

Business Technical Functional Information

requirements requirements requirements requirements

Examples to Compliance, Value, Available technology, Common use, System Accuracy,

consider for Security, Disaster Existing systems, processes or Circulation,
technical recovery, Reporting Accessibility, performance, Data Usefulness,
documentation functions, Interface Compatibility, archiving, Audits and Copyright,
functions Environment, controls, System Validation,
Hosting, Location administration, Content,
Conversion from one Format,
format to another Deployment
Comments Documents are used The platform for your Can the users capture Does the
for decisions and operating system may information that is process of
reference. The dictate what required, store the documenting
business case for applications can information and information
documents, the manage documents. publish information support the
goals, and the scope Also, available as required, and move information
of documentation hardware, software, information to other needs. Does the
and sponsorship of stationery, and domains. system allow
the project are all facilities need to be for changing
interdependent. considered. needs?

Learning guide 32 Date 08-2017 Page 5 of 9

Author: IT Experts
 Training, Teaching and Learning Materials Development

Collecting requirements
Before technical documentation requirements can be analysed they must first be collected. Ideally, the
collector needs to take into account every point of view and fact. The ability to do this will depend on the
time, budget and available resources. A good start would be to interview the person who has asked you to
determine the documentation requirements, to get a clear idea of:
 what result is expected or needed
 the amount of time you have
 a budget for the project
 who will help you
 What authority you will have.
Some techniques to gather requirements include:
 inspecting the documents and their use
 interviews, workshops and use cases
 Sample documents, templates and checklists.
On the internet there are many resources where you can refer to and compare sample documentation systems.
Documentation specialists use several techniques to dig below the surface and get to the core of
requirements. Some of them are briefly described here.

Start with who you know

Interviews with the client, subject expert and major stakeholders are necessary in defining the requirements
for documentation. If you are a part of a large organisation, a larger number of individuals may need to be
consulted. Prepare your questions carefully before you start interviewing.
Ask questions of stakeholders or interview users. On a major project you may be working with a team and
can interview more widely. This will increase the time and cost of the survey, but may reveal discrepancies.
Not everyone will be available for interview. You might send a questionnaire by email, or explore other ways
to get information you need.

Workshops and use cases

Bring people together for a workshop, if possible (it may be hard to get all the experts together at the one
time). Workshops are good for canvassing the problems of documentation, but less productive in producing
solutions.
A use case draws on scenarios that describe how users will interact with the documentation, to achieve a
specific result. It is something like a role-play on paper. Use cases are good for establishing the functional
requirements of documents. A use case considers things like interface between the users and the system.

Learning guide 32 Date 08-2017 Page 6 of 9

Author: IT Experts
 Training, Teaching and Learning Materials Development

Evaluating requirements
When asking clients, users and stakeholders what they believe a document system must have, you can be
silently asking yourself, is this requirement:

Necessary? Can the organisation meet its needs without the technical document? If the answer is yes,
the document may not be necessary.

Supportable? Can the requirement be supported in the documentation system? If not, the requirement
should be checked or changed.

Unambiguous? Can the requirement be interpreted in more than one way? If yes, it’s time for more
interviews or editing.

Complete? Is there anything missing? Better to have stakeholders review the specifications now, than
have problems later.

Dependable? Are there conflicts with any other requirement, or other parts of the system?

Concise? Is the requirement simple, short and to the point?

Acknowledged? Is the source of the requirement documented? Are reviews cross referred to the source for a
double check?

Identified? Can other people readily find and identify this requirement, in case of later need for
amendment?

Reviewing requirements to come up with specifications

Once you’ve heard what everyone believes they need from the documentation, you must analyse the data.
First, break requests into distinct requirements. If one person proposes that a document must do ‘A’ and ‘B’,
each proposition must stand alone, so that it can be accepted or rejected on its merits.
Look for unanswered questions, and find the answers, from one source or another.
If there is a vague requirement, such as a document should be ‘short’, you should go back to the source, and
ask exactly what that means, and why it is important. Don’t assume that you know. Find out what a ‘long’
document is.
Combine those requirements that are similar. Categorise them into their system properties, such as function,
form, style, content, etc.
Identify contradictions, and ask the sources to explain.
Prioritise the requirements. There are core requirements, such as features which if missed will affect the rest
of the system. There are requirements that must be included and those that are optional.

Learning guide 32 Date 08-2017 Page 7 of 9

Author: IT Experts
 Training, Teaching and Learning Materials Development

Once you have an ordered and integrated list of needs and recommendations, you should ask the participants
to review your interpretation of their requirements. This document is really the basis for the first draft of the
requirements specifications.

Validating requirements
It is not unusual or unrealistic to expect that not every one will agree with the requirements specifications
that are proposed. There may need to be some resolution procedure in place, if negotiations don’t lead to
consensus. The final word belongs with the client, or project sponsor, to resolve issues and make final
decisions.
Submit a draft of your specifications to select users. Ask them for feedback. Can they comply with these
specifications when they create documents? Ask them to create or amend a document using these rules.
When others use documents created to these specifications, will their work benefit from them or be
constrained?
If you’ve used a reiterative process in forming your recommendations (by circulating drafts, for instance),
and kept participants informed of your reasons, then you should not have too much trouble getting
consensus.
OVERVIEW OF SCOPE OF WORK
A scope of work sets forth requirements for performance of work to achieve project objectives. The scope of
work must be clear, accurate and complete. SOWs have to be read and interpreted by persons of varied
backgrounds, including performing contractors and their suppliers, project managers representing
departments or offices, and the contracting officer. Therefore, the SOW should be worded to make more than
one interpretation virtually impossible.
Developing a scope of work presents unique problems, because each SOW is designed for a unique
procurement action. A normal procurement specification, such as a purchase or supply contract, is used to
procure standard products and repeatedly used services.
But a scope of work is mainly used to procure a variety of nonstandard services, as well as development of
software and hardware, and construction. Thus, no uniform SOW format can be applied, but guidelines can
be followed to achieve an end product that meets the specific objectives of the contract.
The difficult and sometimes controversial function of proposal evaluation and source selection is based
largely on a scope of work, which is the baseline standard for evaluating all proposals, for reconciling them
to design or other requirements, and for determining the best approach to competition. Evaluation criteria are
based on a scope of work that defines project objectives and requirements for their achievement. Challenges
to the proposal evaluation and source selection are almost always traceable to an uninformative or ambiguous
scope of work. Any scope of work must cover the following points:
 What needs to be done
 Who will do what
 When it should be done
 Where it should be done
 How contract performance will be judged
The scope of work may also define how the job is to be accomplished. When objectives are not well
described and defined, misunderstandings are likely. Ambiguous SOWs can lead to unsatisfactory
performance, delays, litigation, and high costs. (Section deals with specific SOW language.)
Scope of Work Format

Learning guide 32 Date 08-2017 Page 8 of 9

Author: IT Experts
 Training, Teaching and Learning Materials Development

Although the elements of a scope of work can vary with the objective, complexity, size and nature of the
work to be performed, a flexible, seven-part format provides a practical approach to document drafting. The
suggested seven parts are:
I. Background
II. Scope
III. References
IV. Requirements include schedules
V. Progress/Compliance
VI. Transmittal/Delivery/Accessibility
VII. Notes
Summary
In this reading, while keeping in mind the attributes of good documentation, you focused on investigating the
goals and needs of an organisation to determine its requirements for technical documentation. The
importance of document control for later processes of design and production was discussed. The basics and
importance of determining document scope and having requirements specifications validated, was also
outlined.

Progress
Have a look at the next section—Activity. If you have trouble, review this reading or perhaps take a look at
some of the listed Resources.
When you feel ready, try the Self check section at the end of this topic. This will help you decide if you are
now able to complete the task and attempt assessment.

Learning guide 32 Date 08-2017 Page 9 of 9

Author: IT Experts