Database Administration Level III

Based on August, 2011, Version 3 Occupational

Standards (OS) and curriculum

Module Title: Creating Technical Documentation

LG Code: EIS HNS3 M12 1220 LO (1-4) LG (43-46)
TTLM Code: EIS HNS3 TTLM12 1220v1

December 2020
Bishoftu, Ethiopia
 Table of Contents
LO #1 - Identify and analyze documentation needs ................................................... 4
Instruction sheet ........................................................................................................ 4
Information Sheet 1 Consultingclient to identify documentation requirements ............. 5
Self-Check 1........................................................................................................... 15
Information Sheet 2 Interpreting and evaluating documentation requirements .......... 16
Self-Check 2........................................................................................................... 18
Information Sheet 3 Investigating industry and documentation standards ................. 19
Self-Check 3........................................................................................................... 27
Information Sheet 4 Defining and documenting scope of work .................................. 29
Self-Check 4........................................................................................................... 31
Information Sheet 5 Validate and confirm the scope of work ..................................... 32
Self-Check 5........................................................................................................... 35
LO #2 - Design documentation................................................................................... 36
Instruction sheet ...................................................................................................... 36
Information Sheet 1 Identifying information requirements with reference to layout and
structure..................................................................................................................... 37
Self-Check 1........................................................................................................... 45
Information Sheet 2 Creating document templates and style guides ......................... 46
Self-Check 2........................................................................................................... 53
Information Sheet 3 Conducting review of the system ............................................... 54
Self-Check 3........................................................................................................... 57
Information Sheet 4 Extracting content that meets information requirements ............ 58
Self-Check 4........................................................................................................... 61
Information Sheet 5 Developing structure of the technical documentation ................ 62
Self-Check 5........................................................................................................... 65
Information Sheet 6 Validating technical documentation structure ............................ 66
Self-Check 6........................................................................................................... 69
LO #3 - Develop documentation................................................................................. 70

Page 2 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Instruction sheet ...................................................................................................... 70
Information Sheet 1 Writing technical documentation ................................................ 71
Self-Check 1........................................................................................................... 73
Information Sheet 2 Translating technical terminology plain English ......................... 74
Self-Check 2........................................................................................................... 82
Information Sheet 3 Applying content format and style .............................................. 83
Self-Check 3........................................................................................................... 91
LO #4 - Evaluate and edit documentation ................................................................. 92
Instruction sheet ...................................................................................................... 92
Information Sheet 1 Submitting technical documentation .......................................... 93
Self-Check 1........................................................................................................... 95
Information Sheet 2 Gathering and analyzing feedback ............................................ 96
Self-Check 2......................................................................................................... 103
Information Sheet 3 Incorporating alterations into the technical documentation ...... 104
Self-Check 3......................................................................................................... 107
Information Sheet 4 Editing technical documentation .............................................. 108
Self-Check 4......................................................................................................... 110
Reference.................................................................................................................... 111
Answer Key Module Title: Creating Technical Documentation ................................... 113

Page 3 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LG#43 LO #1- Identify and analyzedocumentation needs
Instruction sheet
This learning guide is developed to provide you the necessary information regarding the
following content coverage and topics:
 Consultingclientto identify documentation requirements
 Interpreting and evaluating documentation requirements and confirming with client
 Investigating industry and documentation standards
 Defining and documenting scope of work
 Consulting clientto validate and confirm the scope of work

This guide will also assist you to attain the learning outcomes stated in the cover page.
Specifically, upon completion of this learning guide, you will be able to:
 Consult client to identify documentation requirements
 Interpret and evaluating documentation requirements and confirm with client
 Investigate industry and documentation standards
 Define and document scope of work
 Consult clientto validate and confirm the scope of work
Learning Instructions:
Read the specific objectives of this Learning Guide.
1. Follow the instructions described below.
2. Read the information written in the ―Information Sheets‖. Try to understand what are
being discussed. Ask your trainer for assistance if you have hard time understanding
them.
3. Accomplish the ―Self-checks‖ which are placed following all information sheets.
4. Ask from your trainer the key to correction (key answers) or you can request your
trainer to correct your work.
5. If your performance is satisfactory proceed to the next learning guide,
6. If your performance is unsatisfactory, see your trainer for further instructions

Page 4 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 1Consultingclient to identify documentation
requirements

1.1 Technical documentation

Technical documents use facts, proof and evidence and are designed for use by
technicians; be they systems analysts, statisticians, designers, programmers,
economists, stockbrokers or building surveyors, to name just some specialist areas that
require technical documentation.

Technical documents are more than just user documents. They present specific
information and know-how needed to develop, produce, maintain or use a form of
technology. Technical documentation can be in the form of models, prototypes,
drawings, sketches, diagrams, blueprints, manuals or software, or presented as training
or technical services.

Types of technical documents

Technical documents in business, to name just some, include:
 Investment analysis  Leases
 Cash flow projections  Staff needs forecasts
 Tenders  Marketing research statistics
 Agent contracts  Annual general reports.

In an IT section documents might include such things as:

Table 1
Network diagrams Frequently asked questions

Hardware specifications Account application forms

Service level agreements Change management procedures

Password security policy Commenting in programming

Request for proposal Flow charts.

Page 5 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 The nature of technical resources

Technical reference documents can offer the same benefit as general reference works,
like dictionaries and encyclopedias, to be consulted to solve a particular problem, rather
than to be read from cover to cover.

A technical manual can include properties, methods, events and controls for products or
systems. It can include specifications, definitions and acronyms. Yet few technical
manuals answer all the questions, for all users. They need to be cross-referenced from
one document to another.

Technical resources can range from single-sheet specifications, manuals, CDs, online
data or a small library offering a wide scope of information and covering subject matter
in detail.

The demands of technical readers

Technical readers are critical and hungry for detail, and they tend to be more intolerant
of flaws than in general reference works.

That is because technical manuals or reports may be read and analyzed for a particular
elusive fact, by experts, workers and system users. Readers may need a complete and
intimate knowledge of some systems. In other cases, they many need information to
conduct tests, or to be ready to solve unexpected problems. Readers may need:

 Comparative information for recommendations, conflicts and failures

 Research materials
 Specific data from test reports
 Answers in order to adapt the technologies for configuration in unfamiliar
contexts.

Page 6 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 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 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

Page 7 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 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.

Page 8 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 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.

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 technicaldocuments. 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 2.

Page 9 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Table 2 Version control table

Date Produced by Reviewer Editor Version

25/10/20 TesfayeKasa 0.1

21/11/20 DiribaDagne 0.1.1
28/11/20 TigistFeyisa 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 3

below is an example of configuration management.

Table 3: 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.

Page 10 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Table 4: Baseline control

Name Signature Date

Author
Project manager
Reviewer

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.

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:
Page 11 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  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 5 Outlines and comments on types of requirements for technical documentation.

Table 5: Categories of requirements

Business Technical Functional Information

requirements requirements requirements requirements

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

consider for Security, Disaster Existing systems, System 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

Page 12 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Comments Documents are The platform for your Can the users Does the
used for decisions operating system may capture information process of
and reference. The dictate what that is required, store documenting
business case for applications can the information and information
documents, the manage documents. publish information as support the
goals, and the Also, available required, and move information
scope of hardware, software, information to other needs. Does
documentation and stationery, and domains. the system
sponsorship of the facilities need to be allow for
project are all considered. changing
interdependent. needs?

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

Page 13 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 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.

Page 14 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 1 Written Test

Directions: Answer all the questions listed below.

I. Choose the best answer
1. Are any of the following categories of requirements that should be considered for
technical documents?
A. Business requirement B. Technical requirement
C. Functional requirement D. Information requirement
E. All of the above
2. Which of the following would not be an attribute of a good document?
A. Contains factual and correct information
B. Includes headings, subheadings, indexes and table of contents
C. Careless use of fonts and page design
D. Contains only relevant information
3. Revision control of your technical documentation is not important for all technical
documentation.
A. True B. False

II. Write appropriate answer for the following question.

1. How is technical documentation different from user documentation?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.
Name: ___________________ Date: ____________ Score: ____________

Page 15 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 2 Interpreting and evaluating documentation
requirements

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.

Page 16 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 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.

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 everyone 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.

Page 17 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 2 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.
1. What is the audience that technical documentation is written for?
2. What are some questions that you may ask to gather requirements about your
technical documentation?
3. What are some techniques that you can use to find out your requirements?
4. How might you consistently ensure your documentation has the necessary
information included for good version control?
5. List at least 3 document evaluation requirements?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 18 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 3 Investigating industry and documentation
standards

1.3 The principles of good documentation

Good technical documentation clearly conveys its subject matter without errors or
ambiguity, and by being easily and quickly comprehended it meets the demands of
technical readers.

While specialist terms are necessary, plain English makes technical writing easier to
read, and glossaries can help explain terms. Unexplained or overused jargon is a
common fault of technical writing.

Many technicians, understandably, develop the bad habit of using overly-specialist

terms or jargon that no one else understands. While some terms are needed, jargon
can mask meaning and make technical writing dense with nouns. Much of the jargon
used in this way is picked up in the first place from poorly written documents.

Most noticeably, a well-planned and written technical reference will have ‗chunks‘ of
information. The chunks will be well mapped and indexed, to allow users to find a
particular fact. And facts with a relationship will be cross-referenced, from one to the
other. Up-to-date and complete technical documentation can save hours of later
questioning.

Attributes of good documentation

Table1 itemises typical features of well-structured and well-expressed documentation.
Table 1: Features and characteristics of a good document
Details

Contents Show the user at a glance the overall contents and structure of the
listings document. In text documents this could be a table of contents, or
can also be supported by an index in longer documents, especially
if the users might need to find specialist topics or sub-topics not
listed in a table of contents.
Stated purpose If the purpose of the items is provided a user can quickly start
accessing what they need.

Page 19 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Navigation tools A well-developed system of navigation includes features such as
colour coding, table of contents, dividers, drop-down menus and
icons and indexes.
Accurate It should contain factual and correct information.
Accessible In structure, it should include headings, subheadings, indexes and
table of contents, etc. The language should also be clear and
without unexplained jargon; if necessary, glossaries should be
included to explain jargon and to spell out acronyms.
Clear It should be easily understood by the intended audience without
ambiguity in meanings.
Coherent It should cohere through the logical association of all the parts to
each other.
Concise It should be concise in that it should contain only relevant
information
Complete and It should be completeall aspects of the aim have been addressed,
comprehensive and comprehensive in that it should have all information on the
subject.
Consistent It must be consistent in the manner of style, format and
presentation, including in the use of terms and spellings etc.
Objective The writer must be impartial and not introduce personal opinions.

Common faults in technical documentation

Table 3.2 could be used as a checklist against which documents are planned, as the
basic requirements for good documentation. Table 2 on the next page lists common
faults that would need to be corrected if found in drafts of documents or documents
already produced and being reviewed.

Page 20 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Table 2: Documentation review—checklist
Attribute that needs to be corrected or improved Yes No

Poorly stated objectives and or purpose  

Inappropriate physical structure and layout  

Inadequate explanations and descriptions  

Difficult language  

Costly methods, processes and production  

Poor quality of pictorial and written text  

Mismatch between the user‘s information requirements and  

the documents technical content
Lack of instructional information in tutorials  

Careless use of fonts and page design  

Documentation standards

Good technical documentation is written and structured within a framework of specific

standards. Documentation standards provide guidelines for producing documents as
well as for their reproduction or delivery to users.

Figure 3.1 below illustrates how standards are an essential starting point for creating
technical documentation and are applied to the design of documents and their later
development and production. Standards also apply to client sign-off on technical
documentation.

Page 21 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Figure 1: The place of standards in creating technical documentation

Standards should in the first place help determine:

 What a document should provide

 What terminology should be used

 How the documentation should be presented and laid out.

The standards that you apply to your documentation will vary depending on your
industry, your organization, and even the particular project. The whole idea of standards
is to ensure consistency and quality.

Standards are set both by industry and the organisation for which you work. You‘ll need
to determine what those standards are. One way you can start to do this is to critically
examine a number of good examples. It is also true to say that these can standards
change over time along with business practices.

Page 22 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Standards are essential for producing good documentation. They provide guidelines on
what content to include, the writing style and the format of the document. Standards
make it easier to develop, use and maintain documentation.

Industry standards

Industry standardsare generally adopted by organisations to ensure documentation they

produce is of good quality. Such standards become organisational policy, and writers,
whether internal staff or contractors, have a basis upon which to produce
documentation.

For example, an organisation usually has clear policies on such things as the layout,
typography, colour and style to be used in any of its documents, so as to project the
correct image. This information would normally be found in a ‗style guide‘. Organisations
may also have standard templates for producing their technical documentation. Often,
during a project, some of the standards are actually specifically developed for that
project.

On-screen and web accessibility guidelines

Technical documentation online, or in an on-screen format can ease problems of

access to information for disabled people. Text on a screen can be enlarged, and text-
to-speech converters can read from a screen. In using on-screen technologies for
documentation you must keep in mind that:

 Electronic text readers and Braille output devices cannot deal with information or
links presented in graphic format

 Audio material is not accessible to deaf people or people with hearing

impairments

 People with impaired vision can find access difficult or impossible with some text
forms and colour use.

Page 23 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 W3C on-screen accessibility guidelines

World Wide Web Consortium (W3C) guidelines include the following recommendations,
which are often used as a standard for publishing online:

 Provide ‗alt text‘ (alternative text) for all images, animations and other active
features.

 Provide captioning and transcripts for audio material, and text descriptions for
video material.

 Summarise or use long description attributes for graphs and charts.

 Summarise tables or make them understandable for line-by-line audio reading.

 In hyperlinks, use text that makes sense when read out of context—for example,
avoid using Click here.

 Use signposting techniques such as consistent headings, lists and other content
structures.

Quality standards (ISO 9000)

Once an organization has decided which industry standards it must keep to, and those
that they would like to adopt, they must develop policies and procedures to ensure
standards are met.

One such standard set is the ISO 9000 family of standards, which require an
organisation to establish and maintain a documented quality system. The standards
give some leeway on how you document that system. In practice, quality documentation
generally has three levels:

 Level 1 - the quality manual, gives a general overview of a quality system,

including a quality policy to explain organisational structure and responsibilities.

 Level 2 - procedures, such as contract review, design control and document

control that the ISO standards require are established and documented.

Page 24 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  Level 3 - work instructions and objective evidence, including specific tasks that
must be performed to follow established procedures, and information in records
and forms to demonstrate the procedures for a task have been followed.

The quality manual

Documenting a quality system can be a big task. If your organisation has chosen to
conform to ISO 9001, for instance, you may document over 40 procedures. When each
procedure has many tasks, work instructions proliferate. Keep in mind that more
documentation is not better: auditors look for the documentation actually needed to
meet quality objectives. It need not be expensive, but it does need to be understood to
be acted on.

The further levels of quality standards, as they apply to procedures and processes, are
discussed in the sections to follow.

Policies and procedures for technical documentation

Most organisations have policies and procedures for the different types of activities they
undertake. Policies help meet standards. Policies and procedures that must be adhered
to for technical documentation may include, but are not limited to areas of:

 Document control and revision Helping to create standards

 Storage If your organisation does not have
 Distribution any policies or procedures for
documentation, then it is important to
 Revision find out why. Perhaps you can make
 Sign-off. it your job to create the necessary
documentation.
Document control and revision

Controlling the development of technical documents is very similar to project

management, or negotiating contracts. In order to ensure the quality and consistency of
documents, clear, manageable and efficient procedures must be in place to handle
version control, change control, document updating and distribution, as the work
progresses.

Page 25 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 The design of any technical document should allow for control of the quality of the work,
and for future changes. Research shows the most frequently cited reason for failure to
earn quality standard certification for technical work is inadequate document control.

From the very start, design your documentation to allow for updating when necessary,
control of changes, and review. Good documentation is enforced through revision
control and checking of the documents by a third party. Copies will be made of your
document, and copies of copies. Can your organisation say where its documents are?
Can it control changes that might need to be made by the document‘s users? If the
document you designed is revised, is there a clear procedure for withdrawing or
destroying all superseded versions?

Procedures and instructions need to be maintained so only designated people can

make revisions. This is a difficult requirement to meet, without proper control of
documents.

Storage and distribution

It is important procedures for the storage are created and adhered to. Depending on the
medium, policies relating to the storage of documents will discuss where documentation
should be stored and how (be it paper-based, on a server or backed up onto a CD).

Once you have identified your target audience and clarified the purpose of the
documentation, you can decide on the most appropriate medium on which to distribute
it. Broadly speaking, documentation is generally categorised as paper-based or digital.

Paper-based documentation is in printed form, and includes user manuals, quick

reference manuals technical manuals and so on—although increasingly manuals are
produced in digital form.

Computer-based or digital documentation may include online tutorials, on-line help,

context sensitive help and read-me documents. Computer documentation may also
contain video (multimedia), and it may also go far beyond the local machine, involving
both a company‘s Intranet as well as the Internet. ‗How to Use‘ videos for instance, are
often used to give a walk-through of a software application.
Page 26 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Sign-off
Standards exist for sign-off processes.

Once you have made all the changes to the document and updated the version of the
document, you then need to ensure that you can get sign-off from all the stakeholders.
Final sign off is usually only granted after the feedback has been incorporated into the
document.

If someone is required to sign-off only the changes to the original document, then you
will have to identify what the changes were to the people who are signing-off the
document.

There are various methods for gaining signoff (which depend on the processes in your
organisation), but the most important outcome is that you have a signature as proof that
someone else has read the material and is happy to take responsibility to allow the
document to be published.

Self-Check 3 Written Test

Directions: Answer all the questions listed below.

Page 27 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 I. Write appropriate answer for the following question.

1. What would you consider are the main advantages of using technical standards for
your documentation? List as many as you can.
2. Give four examples of technical documentation you may find in an IT section.
3. What documentation tools do you think would help you to standardize your
documentation?
4. What are three advantages of computer-based (digital) documentation?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 28 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet4 Defining and documenting scope of work

1.4 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.

What is a project scope document?

A project scope document sometimes called a scope of work (SOW) is a critical piece of
project paperwork that gets teams and stakeholders aligned on the boundaries of a
project before it even begins.

Page 29 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 A well-crafted scope document can save you from major headaches by defining the
following project elements:
 Project goals
 Requirements
 Major deliverables
 Key milestones
 Assumptions
 Constraints
These critical scope aspects enable you to say no more easily when new requests arise
as you‘re trying to deliver a project on time and under budget.
In the end, a well-documented scope statement gets everyone team and stakeholders
alike aligned around these important details that can make or break a project.

Page 30 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 4 Written Test

Directions: Answer all the questions listed below.

I. Choose the best answer
1. One of the following is not included on the scope of the project?
A. Project Fallacy C. Assumption
B. Requirement D. Key Milestones
2. Who Defines The Scope?
A. Project Advisor C. Stakeholders
B. Project Sponsor D. All of the Above
3. What are the success criteria of the project?
A. Short term goal C. Long term goals
B. Big picture oriented D. All of the Above
4. Your project is being carried out under a contract. There have been some changes
in the project scope and you want to determine the cause of variance with respect to
the scope baseline. This will help you decide whether corrective action is required.
This should be done as part of: ‗
A. Define Scope C. Verify Scope
B. Collect Requirements D. Control Scope

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.
Name: ___________________ Date: ____________ Score: ____________

Page 31 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 5Validate and confirm the scope of work

1.5 How to write a scope of work document

There‘s no doubt that a lot of thought, discussion, and sometimes even debate goes
into finalizing a solid scope. But all that work is worth it because having a well-
considered scope document can increase your chances of leading a project to
successful completion.
There are lots of different ways to craft a scope statement. Let‘s take a closer look at
some of the details that go into a solid project SOW.

What’s included in the scope of a project?

Here‘s a list of possible elements you should consider adding to your scope statement.

Business case and goals

Every project has goals, and this is where you‘ll define them. This section typically
includes the reasons the project is being supported (or funded), along with a set of
business goals or intended project outcomes for your team to keep in mind while
executing the project.

These details are critical to document because there will be times when stakeholder
(and sometimes even team) requests creep in and put your timeline and budget at risk.
But you can push those risks away if change requests don‘t meet the documented
business case.

Project description and deliverables

This one is simple: a plain language overview of the project‘s deliverables. Avoid
confusion by clearly outlining what will be delivered for approval through the course of
the project, as well as the final deliverable.

For instance, if you‘re creating a television ad for a client, you might say something
like: Company Name will produce and deliver one 60-second video advertisement in
AVI format to be used on television.
Page 32 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 It‘s a simple description of what you‘re working to deliver, but it also spells out small
details like the quantity, amount, length, or whatever other aspects accurately describe
the project.

Acceptance criteria
Your scope should help you come to an agreement on what will be delivered and leave
no question when the project is complete. Acceptance criteria can be measured,
achieved, and used to prove that work is complete.

Examples of some of the conditions or criteria of acceptance can be found in project

requirements, user acceptance testing, or even just a final stakeholder review and
approval.

Limitations
Every project has its limits, and you need to be sure you‘re not exceeding those limits to
complete a project on time and under budget.

Limitations can come in many forms, but one example would be technology. For
instance, if you‘re building an application that depends on a specific technology, be sure
to mention that. There may be several ways to code that website, but if you‘re boxed
into a complicated technology, you can cover yourself by specifying those limitations in
your scope.

Doing so will help you when you run into a limitation and don‘t have the time or budget
to explore alternatives. Think of it as an insurance policy for your project.

Assumptions
You know what they say about assumptions, and you probably know it‘s true. If you
don‘t outline them, you‘ll end up with confusion, missed expectations, and project
problems. So take time to list out all the assumptions you‘ve thought about that will
affect the work you‘ll do or the outcomes of that work.

Page 33 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Exclusions
You‘ve already listed out the deliverables you will provide, but sometimes it‘s just as
important to itemize what you will NOT deliver. This helps you avoid awkward ―But
weren‘t you going to…‖ questions or requests. Really, it‘s about setting expectations
and avoiding any miscommunication around the work you have planned.

Costs
This is an optional portion of your project SOW, depending on the type of organization
you work in.

If you‘re part of a consulting agency that charges external clients for your work, you‘ll
want to outline project costs, possibly even on the phase or milestone level.

You have to do what feels right for your project and organization. But the clearer you
can be about costs and the work associated with it, the easier it will be for you to
manage it and make a case for more funds when additional scope creeps in.

Agreement
Scope documents create agreement by nature, but sometimes you need proof! So
include a signature field in your scope document and have your lead stakeholder or
project funder sign the document.

On that note, it‘s important to remember that if you‘re collecting money for the work or if
there are high stakes you‘ll likely want to have your scope document reviewed by a
lawyer before it‘s signed. After all, the scope document is a contract.

Page 34 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 5 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. What do we mean by project constraint?

2. What are the project‘s deliverables?
3. What‘s out of scope?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 35 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LG #44 LO #2 - Design documentation
Instruction sheet
This learning guide is developed to provide you the necessary information regarding the
following content coverage and topics:
 Identifying information requirements with reference to layout and structure
 Creating document templates and style guides
 Conducting review of the system
 Extracting content that meets information requirements
 Developing structure of the technical documentation
 Validating technical documentation structure

This guide will also assist you to attain the learning outcomes stated in the cover page.
Specifically, upon completion of this learning guide, you will be able to:
 Identify information requirements with reference to layout and structure
 Create document templates and style guides
 Conduct review of the system
 Extract content that meets information requirements
 Develop structure of the technical documentation
 Validate technical documentation structure
Learning Instructions:
Read the specific objectives of this Learning Guide.

1. Follow the instructions described below.

2. Read the information written in the ―Information Sheets‖. Try to understand what
are being discussed. Ask your trainer for assistance if you have hard time
understanding them.
3. Accomplish the ―Self-checks‖ which are placed following all information sheets.
4. Ask from your trainer the key to correction (key answers) or you can request your
trainer to correct your work.
5. If your performance is satisfactory proceed to the next learning guide,
6. If your performance is unsatisfactory, see your trainer for further instructions

Page 36 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 1 Identifying information requirements with
reference to layout and structure

2.1 Audience, purpose and function

Before you start designing a document you must know (or make assumptions about):

 who will use the documents

 what they will use the documents for, and how they will use the documents

 what they are expected to do with the information in the document

 if they will read the entire document, or just the parts they need quickly

 if they need access to technical information for quick reference.

Your reasons for documentation will affect your design. For example, you may be
documenting procedures and policies for quality control.

The design of technical documents includes deliberate choice of:

 Genre (what type of information?)

 Function (how will the information be used?)

 Structure (how the information is made accessible?)

 Content (what level or depth of understanding you will provide; if the publication
or product is for beginners or experts, for building or for maintenance)

 Format (how it will it be published, as a book, paper, file or web site)

 Style (including the use of illustrations, text, data and language)

 Tone (will it be intended as a reference or explanatory object).

Content distribution—what goes where

You may consider a system of publications, with both sequential and selective access.

Page 37 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Experts in a company may need technical documents for reference, for instance, and
need to find a particular fact directly, or a measurement in the middle of pages of other
specifications. They don‘t need to read the whole history of the product. For
maintenance, a technician needs to find a procedure quickly, without all the solutions to
other problems. They need to access information selectively. A new employee however,
might need to read more; they need to know about the product, and the processes, and
the reasons. The learner may need to read sequentially.

In designing documentation to distribute the content across different documents, you

need to decide how the content of each publication might overlap.

Other considerations
Depending on your role, you may also consider the following issues as you design your
technical documentation:

 Publisher: Who is in charge of ensuring this publication meets its goals and
reaches its audience needs?

 Author: Who will write or provide the content for this publication?

 Rank: How does this publication rate in relative importance to others that you
have to produce?

 Functionality: What functions will be built in (especially if it is online, for instance,

the use of form fields, java script).

Structure and navigation

Principles of structure

Structure is important to help readers understand the content of a document. Structure

is especially important for technical documentation, where information is best organised
into chunks. With more and more documents available in electronic form, onscreen
(online or on CDs of DVDs) and connected through hypertext, decisions about structure
become even more complex. Yet fear not, some easy to understand principles of logic
in organising material remain.
Page 38 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 The structure of a document helps place emphasis on content where emphasis is
needed, and it arranges the order of information by importance or by necessary
progression or sequence (for procedures and instructions, etc), or both.

When designing the content of technical documents, your aim is to break complex
information into its most basic elements and then present those elements to readers in
such a way that they can quickly and easily scan and retrieve the information they need.

Give your readers the option of reading to the level of detail they need. If the users of
your document are experts, they want to go straight to a particular fact, or instruction.
An expert may not need to read the whole document. Don‘t force them to sift through
detail in order to find the main point. Important details need to be where they can be
found if needed.

The flow of information

The most basic way of organising information is by a hierarchy of importance, using a
hierarchy (or labels) with the higher level having a larger font). Hierarchical presentation
begins at the top level, which is general, such as an introduction. Like an upside down
tree branching (or like tree roots), the information works toward the lowest level, which
is more specific and detailed.

With three heading levels, for instance, you would:

 Begin with an overview of the entire topic under a level 1 heading

 Identify each block of information with a lesser, level 2 heading

 Describe each block in detail, one at a time, under level 3 headings.

Headings (or titles or captions or information labels) should always be descriptive,

specific and informative. They tell a reader or user for what to expect in this block of
information and help them to find specific information quickly, and if necessary, in
isolation.

Each block of information may in turn consist of smaller parts, organised around a
single subject and having one clear purpose, and expressed in paragraphs, each of
Page 39 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 which develops a single idea in two or three sentences (or as many as are needed to
cover the idea).

Mapping information
Search and reference features

In technical documentation, listing contents for easy access and reference is also
needed, which can include the features in Table 1.

Table 1: Document components and features that aid reference and use

Tables of contents A table of contents lists and reflects the hierarchy of main and minor
headings in a document.
Indexes An index has keywords, terms or names that are essential for users to find
a subject or detail, or for people seeking that information, to find your
document on the web. On the web, even if your document is only a few
pages, you may need about 50 key words to help search engines find it.

Glossaries Glossaries can include key terms, specialist terms or terms likely to be
new to readers or users of the document; glossaries can also include a list
that spells out acronyms used.
Cross references and In print documentation cross-references might include page numbers, and
hyperlinks for digital documents hyperlinks can perform this function in addition to
providing links to other documents.
Full text search For documentation on web pages a search facility might be designed to
aid use and access to topics and sub-topics by users.
Structural consistency You should arrange the structure of different technical documents within
across documents an organization the same; users then quickly know how to use that
document.
Integrated graphics Graphics help interaction with readers and users. Integrated graphics
(often charts or drawings) are those placed near text that relates to them
(instead of having them off in another part of the document, such as in an
appendix).

Structural ordering of traditional and longer documents

The structure of longer documents needs even more detail to help users find the
information they need. Broadly, with larger documents, information can be divided into
the three-parts of front matter, body matter and end matter.

Page 40 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Front matter

Front matter is organised according to what makes best sense for the use of
documentation. Some of the common features of upfront material in documentation can
include:

 Title page stating what the document is about, and the revision level, such as
version 1.0

 Copyright statements standard for all documents

 Notes of revision level, stating the history of document revisions

 Configuration management tables which would show where the original copy of
the document is kept, where a hard copy is available and where on the network
server to find a soft copy

 Baseline control tables, which is used by the document writer, the project
manager and the subject expert to sign-off on the document

 Tables of contents, which can be produced and updated automatically in word

processing applications

 Prefaces, which are often an introduction, kept to one page and are a summary
of the document‘s contents (an executive summary or an abstract can sometimes
be used with longer documents).

Body matter

The body of the document is its substance. It is the content, ordered into parts or
sections of chapters (or some combination, depending on the length or page extent of
the documentation). In print material, headings within the body of the document would
be listed on a table of contents and these would be hyperlinked in online or digital
versions.

Page 41 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 The principles of a structure discussed above apply to the body of the document (having
it ordered under a hierarchy of headings and with a logical progression), which then can
include a range of media for information and data, diagrams, tables and graphs.

Appendices are often part of the body of a document in technical documents (though
they can also be treated as end matter) and include tables, or raw data or other sets of
technical information that support explanations or procedures in the text.

End matter

End matter (as mentioned) can include appendices and attachments that support of
explain subjects in the body of the document. A glossary of terms can also be placed in
end matter, for readers unfamiliar with or new to technical words in the document, and
to explain acronyms used. If the document is long enough, a separate list of acronyms
might be included.

An index is standard for all long documents; word processing applications can help the
writer sort information for an index, although often, especially when documents are
typeset in page layout programs, the index is created when the pages are final, and is
done by specialist indexers. Indexes on web sites serve a different purpose of people
being able to find your document online from a range of terms.

Presenting different types of information

Writers learn that once they have classified their information, questions of presentation
(in what way or form should it be presented?) start to appear. Table 2 shows some
established ways of presenting information types.

Table 2: Some established ways of presenting different types of information

Information type Best presentation method

Classifications Lists and tables

Structures Charts and drawings
Procedures and instructions Action tables (concise, sequentially numbered instructions, each
beginning with an action word) and flow charts

Page 42 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Using flow charts

Flow charts are often used to illustrate documents for procedures and work instructions
because they force the reader to think in terms of simple elements or steps. Procedures
are visualised more quickly than in text descriptions, which makes flow charts a faster
way to present and to assimilate information.

Flow charts are also easier for quality engineers, employees and auditors to
understand. Technicians and engineers can map out procedures quickly and review
them for accuracy before completing more detailed documentation.

A simple draw toolbar in word processing applications can help produce flow charts.
Table 1.3 shows commonly used symbols.

Table 3: Commonly used flow chart symbols

Beginning step Decision choice

Process Inspection

Decision point Ending point

Document Preparation

Using graphics

Technical readers are in many ways visually literate; visual elements are a part of
learning technical subjects and are expected in technical documentation.

Text alone is not enough in complex technical documents to make meanings clear, and
even in basic documents illustrative material can include a range of graphics. Intelligent
use of good quality graphics is important to the design of technical documents.

Page 43 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Graphics help achieve documents that can be used for quick reference. Graphics are
easier to remember than words and can be aids to memory they also help people with
reading, language and vision difficulties. The use of graphics can also cater to readers
and users with different learning styles.

Avoiding bad graphics

In many technical documents the best on graphics offer are poor quality and
inappropriate screen shots. Reasons for bad graphics range from editors not wanting to
spend money for a graphic artist or photographer as well as a writer, or fear of copyright
breaches (easily committed with graphics).

Many documents use graphics poorly. Graphics are often distorted to fit an available
space, rather than be given a space of their own. The text is often separated from the
illustration and few document managers have any training in illustration.

Finding the right balance

On the web the reverse occurs, with an artist or designer creating great graphics where
the associated text is poor. A balance between words and images is necessary for
good communication; quality graphics can lessen the need for text, and yet the text then
used needs to be precise, concise and well expressed.

It becomes especially important that graphics used on web pages are such that an
international audience can relate to and understand them. Use of line illustrations,
photographs and screen shots are effective only when they are understood and convey
the proper meaning. Always consider how readers of different cultures will interpret
colours and symbols, etc.

Page 44 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 1 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. For what purposes might you design technical documents at work?

2. Define a technical document?
3. What might the ‗body matter‘ section of a longer technical document include?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 45 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 2 Creating document templates and style guides

2.2 Styledocuments

Style can refer to the way a writer organises sentences.A good style for technical writing
is brief (using only as many words as needed), clear (having no ambiguities of meaning)
and precise (grammatically correct and always choosing the simpler and more direct
form of sentences and paragraphs).

Stylealso concerns typography or design; how a feature is placed, or is styled. The

different features of a template for instance might be called ‗styles‘; heading styles,
styles for body text, etc. A certain style is used at certain times. In templates, those
formats are then recorded on a style sheet.

Style is also the set of publication conventions, such as whether book and movie titles
should be written in italics; expression of dates and numbers; how references should be
cited. The document that is kept as a record of conventions used for a particular
document is also called a style sheet.

Style guides and manuals

Style guides are often written for particular organisations or publishing houses (to
specify a ‗house‘ style). Rules of style can include consistency in the use of typography,
layout, word choice, spelling and punctuation. Style guides list all manner of
conventions to be used to adhere to a corporate image and a consistent way of
producing and presenting documentation.

Style manuals generally have much more comprehensive information, such as detailed
advice on publishing in both print and electronic formats; or information on the general
practices in editing, design, electronic publishing, indexing and printing fields, for
instance. Style guides often contain three types of information:

 Process (how things are done, for example, how to create a document and get
it approved for publication)

Page 46 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  Design (documents appearance to conform to the business image)

 Style (the house style, and if there is a template to use).

Keys to the creation and maintenance of a successful style guide include:

 An effective requirements process, in gathering information

 A keen team of stakeholders and ways set for the guide to evolve.

A style guide has rules and suggestions or recommendations to be followed when

producing a document. Style guides help ensure consistency in presentation (titles,
headings, sub-headings, etc), vocabulary, style and layout. What should be rules (that
are non-negotiable) and what should be suggestions depends on organisational policy.
Thus, the rules will vary from one organisation to the next.

Style guides are regularly updated to reflect current business needs and policies, as
well as changes in style over time. They are then circulated to all who may be affected
by the changes. Style guides are often accessed on a company‘s intranet site where the
digital copy can be easily kept up-to-date.

Style guides usually apply to all documentation or in some cases a guide might exist for
technical documents. The style guide should contain design decisions that directly affect
writing and editing, for example:

 The conventions to be used on chapter and section and page numbering

 Heading styles; titles for figures and tables; the layout of vertical lists

 The rules for highlighting text (bold, underline or italics)

 Which template is to be used for which type of document

 Which version of English to use (American or British)

 Which system of measurement to use, if not metric, and specifying any variations
(for example, ‗dots per inch‘ in a metric guide)

 Mandatory reference materials like an industry style guide, a particular dictionary,

the company‘s design and process guides
Page 47 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  Which elements such as title page, preface, table of contents, glossary, index,
copyright details are required, and what to include in them

 Where headers and footers appear and what they should contain

 When to spell out numbers and when to use numerals as well as defining the
punctuation to be used in numbers over 999.

 Writing style, level of language usage

 Any special requirements or any terms that should be avoided.

Style sheets for documents

Style sheets for are referenced to style guides and record all decisions made for a
particular document. A style sheet may record:

 how a word is spelt, hyphenated or capitalised when several versions are common
or correct

 conventions for typography, font usage such as typefaces and sizes and use of
borders

 any deviations from standard punctuation, spelling or usage

 if figures are centred or flush left, on the page or within the column

 page size and margins, number of columns, offset style (if used)

 bullet characters, including whether and when to use non-standard bullet styles or
more than one bullet style

 if list numbers in procedures have a period after the number

 use of horizontal and vertical rules in tables of data.

An organisation might keep style sheets for individual documents. When another person
works on a document, they have a record of spellings and usage, as shown in Table 1.

Page 48 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 The advantages of using a style guide

Style guides used together with templates (discussed next) can:

 enable consistency within documents and allow a consistent presentation of

information across all business units

 create a familiar ‗tone‘ so that published documents conform to the business

image and policy, including legal requirements

 provide a common vocabulary

 provide an orientation or training aid for new employees or new members of a

production team

 define which style issues are negotiable and which are not

 remove the repetition of the decision-making process in the reproduction of

common elements.

The use of templates

Templates are documents, much like a stencil or a model, which can be used over and
over again without changing the original. Templates are a special type of document that
can hold text, styles, macros, keyboard shortcuts, custom toolbars and AutoText
entries.

A document created using a template will have access to all of these features added
when the document was created, saving the user the work of setting up, formatting and
adding features. All the user needs to do is add the content.

Most applications include forms for the most used documents as templates. Many web
site managers who are not programmers, or use mark-up languages like XML and
HTML, use templates.

Page 49 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Advantages of using templates

A template saves the experts who must write or draw content for publications from the
work of designing and formatting every document individually themselves. Instead, they
can concentrate on the quality of the information.

Templates that conform to the style guide and style sheets have the advantages of:

 prompting the user to include all relevant information

 creating a document in an acceptable format or layout

 creating consistent documentation across the organisation

 facilitating the handover of projects in the event of personnel or organisational

changes

 saving time and potentially costs to create documents

 reducing trial and error and ensuring greater accuracy

 reproducing a design and functionality that is already tested and proven.

Formatting and templates

Format refers to the properties, particularly visible properties, of a document. For

example, word processing applications allow you to format text, which involves
specifying the font, alignment, margins, and other properties. Format and typography
help make the structure and progression of documents more easily understood.

Two very different rules that apply to document formatting are that:

 The format must be consistent; the appearance of content should be uniform from
one document to another, so that the parts and elements work the same way for
the user (and the writer and subsequent reviewers and editors).

 The content is not wholly dependent on the format,so that you can re-use or
convert the content to different media—such as a web site or a manual.

Some decisions related to the format of your document include:

Page 50 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  Files: do you deliver the document as a single file, or will it be many files? This
applies to web documents and longer publications.

 Style sheets: What automatic styling have you set up in the application you are
using the make the documents, to ensure formatting is consistent?

Templates are also an important part of the design of technical documentation, since (if
used correctly) they allow for the automatic and consistent styling of structural items and
features, such as:

 different heading levels

 text types for body text, extracts, footnotes and references

 text features such as lists

 other features such as marginalia and equations

 Automatic table of contents generation.

An organisation may have a general template for technical documents (whether

traditional documents or web pages, designed so that one converts to the other), or they
may have different templates for different purposes. The templates used will usually
also support and reflect a particular corporate or business image.

Good web page design uses style sheets called cascading style sheets (CSS). A
cascading style sheet allows one style guide to apply formatting automatically to all the
pages and content in the web site.

Templates for different parts of a process

Templates help work out some design issues in advance so that documents follow
general principles. Many organisations provide writers of technical documentation with
templates that also include advice and notes about structuring material and how much
information is required in what places.

Page 51 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 The structure of documents needs to be especially clear and logical and templates can
help ensure that written material from experts needs less work before it is subject to
editing and review.

Other templates (without the writers‘ template instructions, etc) might then be used for
further work on documentation to prepare it for publication.

A guide or instructions for using templates—explaining functions of all the different

features and how to apply or use them—is often a part of an organisational style guide.

Page 52 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 2 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. What is a style guide?

2. What is the difference between a style guide and a style sheet?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 53 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 3 Conducting review of the system

2.3 Managing the technical documentation tech review

The accuracy of your organization‘s technical documentation benefits your company

and customers by offering a credible resource for how to use your product. Inaccurate
and outdated documentation can hobble internal development efforts, and negatively
affect external customers as well, when they cannot resolve their own issues by
consulting the documentation that accompanies your product. Your company's
credibility is also damaged, because the customer develops doubts about the product,
thanks to the inaccuracies encountered in the documentation.
A lack of accurate and accessible information also increases the learning curve for new
developers and other technical staff. Here are some tips to help improve the technical
accuracy of the documentation produced by your development team.

Develop a technical review checklist

Many developers and managers lack experience in how to technically review a

document. Here are some points to include in a review checklist to keep the reviewers
on track and focused on the technical accuracy of the documentation:
 Focus on the technical facts to verify that the technology works as documented.
A technical review is not an editorial review.
 Verify the technical accuracy of all procedural steps included in the document.
 Verify the technical accuracy of all screen captures in the document.

Build accountability into the document review process

One of the reasons technical reviews are often disregarded is because no accountability
is built into project plans for technical reviews. Strategies for building accountability into
technical documentation reviews include:

 Add the name of the author(s) and technical reviewer(s) to the documentation.
Some companies have a policy against naming staff, but including author and
reviewer names promotes communication with internal staff. For external audiences,

Page 54 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 such as user guides for commercial, off-the-shelf software, including the author and
reviewer names recognizes the contributions of the development team.
 Make technical reviews of documentation part of the annual review process for
developers.
 Assign technical reviewers for documentation in the project plan.
Raise the accuracy bar for technical writers
While the job title technical writer is subjective in many organizations, the persons in
these positions must have a stake in the technical accuracy of the documentation they
develop, since it is their primary task.
Managers should set the appropriate technical accuracy level that writers are expected
to maintain. While some technical writers may balk at increased expectations about
their understanding of the technology, increasing their stake in the project is a win for
everybody. If the writers are not able to meet the higher standards, you may need to
review the role of your technical writers as compared with your corporate strategy and
client requirements.
To assist technical writers, you need to level the playing field by enabling writers to dig
deeper into the technology: Managers should:
 Involve the technical writers in design and development meetings about the product.
 Involve technical writers in the development of technical requirements, functional
specifications, and design documents.
 Include technical writers on any development group mailing lists.
 Provide access to internal releases of the product during the documentation
development cycle. It can be easy to become cloistered as a technical writer and
rely only on interviewing the experts, but enabling them to become ―hands-on‖ with
the product can provide a new perspective that developers and project managers
may not be able to see for themselves.
 Encourage the technical writers to read more about the technologies behind your
products. For example, if you develop Java-based applications, encourage the
technical writers to become more fluent in the Java programming language.

Page 55 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Set priorities for busy, but key, developers
While many of us have to do more with fewer resources these days, these developers
were spread thin even when times were good, due to their exemplary knowledge and
work ethic. Here are some tips on how to manage the documentation review you need
from these busy developers and ensure their knowledge benefits the documentation:

 Forget about having them review the documentation from cover to cover.
 Work with the document authors to identify the sections of the document that
absolutely must be reviewed by this person.
 Work with them and their management to obtain some uninterrupted blocks of time
to review the document.
 Provide the reviewer who has a stretched schedule with a list of exactly what you
need them to review in the document. Assure them that other team members are
reviewing the rest of the document, and their review input is absolutely necessary for
the sections that relate to their direct area of technical expertise.
Building the better technical review
A thorough technical documentation review benefits both external and internal
customers. While some technical staff considers conducting these reviews a chore,
managers face the challenge of setting priorities to enable a thorough review process
while maintaining critical development efforts.

Page 56 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 3 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. How do we develop a technical checklist?

2. Who is benefited from a good technical documentation?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 57 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet4 Extracting content that meets information
requirements

2.4 Copyright basics

Copyright is the exclusive right of the creator of material to reproduce, adapt, publish,
perform and communicate that material. Copyright can be thought of as a bundle of
rights that can be traded by the copyright owner. Copyright is designed to reward and
provide incentives to creators of copyright material.

When you are designing technical documentation you should allow for any copyright
requirements. Many organisations have copyright rules. In larger organisations there is
often a whole department responsible for copyright.

Two issues about copyright for you to consider are:

 The copyright that you or your organisation might own over information in
technical documents that you have created

 Your obligations when you need to use information produced by other

organisations or creators.

protected by copyright

The Copyright Act 1968 gives protection to two broad categories of material ‗works‘ and
‗subject matter other than works‘. Works are further divided into textual (literary and
including computer programs), dramatic, artistic and musical works. Material described
by the cumbersome phrase ‗subject matter other than works,‘ includes cinematograph
films, sound recordings and broadcasts.

As you can see in Table 4.1, a broad range of materials can be subject to copyright.
Technical documentation might include reports and computer programs, drawings,
diagrams, photos and maps (under ‗works‘), and in materials in the form of film, video,
DVDs, Flash animations, CDs, audio tapes and books (under ‗subject matter other than
works‘).

Page 58 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Table 1: Types of materials protected by copyright

Works Examples Subject matter Examples

other than works

Literary novels, poems, song lyrics, Cinematograph films, videos,

newspaper and journal films DVDs, Flash
articles, essays, reports, animations
computer programs
Dramatic screenplays, stage plays, Sound recordings CDs, audio
choreography cassettes
Musical songs, music as distinct Broadcasts television and
from lyrics or recording of radio broadcasts
music
Artistic paintings, drawings, Published editions books,
diagrams, cartoons, photos, magazines,
maps, sculpture newspapers
What copyright doesn’t protect
Copyright doesn‘t protect intangible things such as ideas or concepts only the material
expressions of those ideas or concepts.

Ideas, information, styles and techniques can‘t be copyright. Names, addresses, titles
and slogans are generally regarded as being too small or unoriginal to be protected as
copyright works. People and images of people can also not be protected by copyright.

The public domain

Public domain works are also free of copyright. The public domain is made up of the
body of knowledge and innovation (especially creative works such as writing, art, music,
and inventions) in relation to which no one can establish or keep proprietary interests
(holding licenses) or ownership. Public domain materials are considered to be part of
the common cultural and intellectual heritage of humanity, which in general anyone may
use or exploit. Works are in the public domain when copyright expires.

Copyfree and copyleft

The term copyfree is used informally when on object is free from copyright protections,
and may be copied, changed or distributed freely. For technical documentation copyleft
describes a group of licenses applied to works such as software and documents. A

Page 59 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 copyleft license uses copyright law to ensure that every person who receives a copy or
derived version of a work, can use, modify, and also redistribute both the work and
derived versions of the work. Authors want copyleft to apply to their work when they
wish to encourage and invite a wide range of people to make ongoing improvements
and elaborations to the work. Copyleft is one of the key features distinguishing several
types of open source software licenses.

Granting and seeking copyright permission

As a copyright owner you also have the exclusive right to authorise others to use your
copyright material in ways protected by copyright.

Using the work of others

On the other hand, if you use copyright material in any way that is protected by
copyright, you must seek the permission of the copyright owner, explaining exactly how
the material will be used and what acknowledgement of it use will accompany the
material.

Educational use and non-commercial use

Under the Act, some copying for educational purposes is also permitted if the institution
has license arrangements with the Copyright Agency Limited.

Most institutions holding archives of images allow students or individuals to use images
for study of personal use (in files downloaded) if the source of the image is properly
acknowledged. Formal copyright permission and the payment of user fees are required
for any commercial use of images.

A note of caution

The information here is only general if you have concerns about legal issues or
practices with copyright, you should consult a legal advisor.

Page 60 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 4 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. How is copyright created and how long does copyright last?

2. What is the difference between copyfree&copyleft?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 61 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet5 Developing structure of the technical
documentation

2.5 Digital document design

Both print and onscreen publishing and later replication to CD or DVD format, or to
other portable media, are almost exclusively digital processes.

The reproduction of technical documentation is also increasingly digital. Manuals and

printed materials can be published to support material onscreen in portable media and
online via the web. It is also possible for a combination of portable media and online
publication. When more than one medium is used for the same documentation, some
basic principles are that:

 the content of documentation should be able to be converted from one media to

another

 allowance needs to be made for onscreen materials to be printed

 the relationship should be clear between print and onscreen materials.

Online and onscreen publishing

Technical documentation is increasingly published on intranet or web sites, or on

portable media, such as CDS of DVDs, to provide onscreen access and the ability to
interact with information.

Internet or onscreen access also works well where technicians and other practical users
travel widely and are that way saved from lugging heavy reference documents. In some
cases where technical information is published onscreen, it may be to the detriment of
printed documentation (with less information being printed). Onscreen publication may
also supplement or update printed technical documentation.

The most basic way of presenting technical documentation online is by material

grouped under headings that are hyperlinked from menus.

Page 62 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Print materials online

It is also common for print materials to be available for download from web sites for
users to print or to read on screen. If layout is important for documents, web pages can
be counter-productive. There may be no guarantee, for instance, that the viewer will see
the document as you intended. Downloadable documents are often made available as
specialist information on web sites, with navigation among HTML pages used to support
broader technical information.

PDF files

Portable Document Format (PDF) files, generated by Adobe Acrobat software, are
intended for brochures, magazines, forms, reports and other materials with complex
visual elements, which will be printed on PostScript printers. They are the most common
format for downloadable files. The format was created to remove machine and platform
dependence for the documents, and its goals include design fidelity and typographic
control. It also functions for online reading to some degree (with hyperlinked contents
lists). Many word processors, page layout and desk-top publishing programs can easily
create PDF files; hence many web sites now make PDF technical documents
accessible for download.

Conversion from print to screen

Converting printed technical documentation for onscreen use involves the following
steps:

 Gathering material (identifying and assembling all the individual components of

the publication)

 Developing the architecture (explained in general terms below)

 Developing access schemes (explained below)

 Developing the navigation tools (the features of the print document can be
refashioned into navigation bars of consoles)

Page 63 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  Constructing the content (the style and structure of the content will be adapted to
the way that readers search, scan and absorb onscreen information, and
converted to a file type such as HTML or PDF)

 Showing relationships between printed and onscreen formats (keeping a visual

connection between printed and online version of documents is important, the tile
page of cover of the printed materials, for instance might be the basis of the
opening screen).

Interactive aspects of design

Technical documentation evolves as technology changes. While the development and

production of documents have times for review and user testing (for both print and
onscreen media), reproduction onscreen means that feedback can be more direct.
Users can more directly influence both use and design, by for instance, providing the
user with diagnostic tools.

The most sophisticated forms of technical documentation include web-enabled

Interactive Electronic Technical Manuals (IETMs), which are a digital package of
information required for diagnosis and maintenance of military and commercial
equipment (including complex weapon systems), and Interactive Electronic Technical
Publications (IETPs) that support complex systems and equipment.

Page 64 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 5 Written Test

Directions: Answer all the questions listed below.

I. Choose the best answer
1. Which of the following is example of a digital document?
A. CDs B. PDFs
C. Online help screens D. Web Pages E. All of the above
2. A usable design includes all of the following design principles except:
A. Shaping the overall page C. Using only the highest quality paper
B. Styling the words and letters D. adding emphasis
3. Effective page design uses ____________________
A. Very little white space
B. Color to provide navigational cues
C. Headings to emphasize the main points
D. A and B
E. B and C

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 65 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 6 Validating technical documentation structure

2.6 Information architecture

The basic principles of structure for documents (breaking information down using
mapping aids, contents lists, headings, graphics and visual elements, especially
typography) still apply to the ordering of information and access schemes on web sites.
Yet the ‗linear‘ aspects of structure (such as the three-parts of front, body and end
matter), no longer apply.

Information sits on different levels of a web site or onscreen hypermedia document,

hence the metaphor often used of ‗drilling down‘ from basic to more complex
information.

Technical documentation onscreen can also feature multimedia, with DVDs able to
incorporate video graphics. As digital video technology and streaming/download speeds
continue to improve, video in technical documentation is bound to rapidly grow. (One of
the common software tools for video documentation is briefly explained, with a link for
reference, in Resources).

Documentation in a range of media may exist across and between a series of screens
and pop-ups on a web site, at different levels. The design or architecture of the site will
determine the pathways and links by which that information is found, where it is placed
and how it is displayed.

Web documents have greater potential for interactivity and a longer shelf life if they are
continually updated and changed. Yet web users are looking for quick, brief information,
and not all types of technical documentation may be best presented this way, without
recourse to more traditional forms (such as also having PDF files etc, at that lower
level).

The principles of good writing do not change when material is on the web or onscreen
(contrary to the impression that so many badly written and unedited web sites might
give you). The only difference may be the extent to which material is broken down into

Page 66 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 small ‗scrollable‘ sections or screens, with relatively short sentences, which is a form
already suited to technical documentation.

When creating a web document, content and structure are emphasised by means of the
information architecture of the site, not simply by the layout of individual pages. Yet the
principle of having all documentation conform to the same broad structure, using the
same styles, applies also to web sites. Navigational design needs to be consistent on all
parts and pages of the site, and on all levels at which materials are placed.

Access schemes

Access schemes are the ways of displaying content in an order or sequence that is
logical for the content and which also accounts for the approaches likely to be taken by
different users of technical documentation.

Things such as tables of contents and indexes can be converted to become access
schemes online. A site map on a web site, for instance, describes aspects of the
information architecture that users need to understand, and works much the same way
as a table of contents does in print materials.

Two types of access schemes are exact access schemes and ambiguous access
schemes.

Exact access schemes

Exact access schemes can provide access to material in categories arranged:

 alphabetically

 chronologically

 sequentially

 geographically.

It is more likely that documents concerned with procedures, such as instruction

manuals, will be arranged sequentially. This is a common approach for technical
documentation design, and it can be supplemented by ambiguous access.
Page 67 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Ambiguous access schemes

This type of access is also common for technical documentation, particularly when
documentation is extensive. Such schemes are termed ‗ambiguous‘ because the way
the headings and material for a subject, topic or process is organised by the writer or
publisher might be very different from the way in which a reader will search for it. While
a manual might specify the logical sequence of events to build a system, for instance, a
technician using the documentation might need information on just one element, and is
unsure of the stage at which that element is discussed. If the different ways a reader
might search are carefully thought about in the design, this type of access can be more
useful.

Page 68 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 6 Written Test

Directions: Answer all the questions listed below.

I. Fill in the blank.
1. Exact and ambiguous access schemes are _____________________________
______________________________________________________________.
2. ___________________ ways of showing content in an order or sequence.
II. Write appropriate answer for the following question.

3. What is metaphor?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 69 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LG #45 LO #3 - Develop documentation
Instruction sheet
This learning guide is developed to provide you the necessary information regarding the
following content coverage and topics:
 Writing technical documentation
 Translating technical terminology to plain English
 Applying content format and style

This guide will also assist you to attain the learning outcomes stated in the cover page.
Specifically, upon completion of this learning guide, you will be able to:
 Write technical documentation
 Translate technical terminology to plain English
 Apply content format and style
Learning Instructions:
Read the specific objectives of this Learning Guide.

1. Follow the instructions described below.

2. Read the information written in the ―Information Sheets‖. Try to understand what
are being discussed. Ask your trainer for assistance if you have hard time
understanding them.
3. Accomplish the ―Self-checks‖ which are placed following all information sheets.
4. Ask from your trainer the key to correction (key answers) or you can request your
trainer to correct your work..
5. If your performance is satisfactory proceed to the next learning guide,
6. If your performance is unsatisfactory, see your trainer for further instructions

Page 70 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 1 Writing technical documentation

3.1 IT technical writers

While specialist engineering technical writers and technical illustrators produce manuals
for buildings, roads, planes, cars, electrical systems, and ships, just to mention a few
areas, many technical writers work within IT and communications industries.

An IT technical writer is any person responsible for writing hardware and software
documentation, online help, technical definitions and technical product descriptions for
publication on paper, or on web sites.

The IT technical writer may be an expert in the subject, with little experience in
documentation, except that learned in training. Or a professional writer may be
employed to help the expert. More often, producing documents falls to programmers
and other developers with little experience or training in technical writing.

Technical writing is necessary for almost anyone who works in IT, communications or
systems. The main skill that professionals among this group of writers bring to their
work is experience in striving to make complicated work simple.

To produce documents that support technology and users you must constantly solve
problems and find answers and solutions.

While documents are assembled, corrected and edited using software applications, and
while it is a technical process, with technical and not imaginative content, is still a
process of creation—an art. You have no automated processes or computers to tell you
if the work is ‗good‘ or not.

Gathering information

Information for technical documents might be acquired by converting it from another

source, collected it from other documents, or by being newly written (on the basis of the
expertise or research from you or other people).

Page 71 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information needed might not have been originally designed for your document; it may
exist in a different format and the language or structure may need to be converted.
Word processing software can also ‗import‘ and ‗export‘ material from other
applications, which might then need to be amended. Information from a database, for
instance, might need some unnecessary content deleted and the work reformatted.

Information may come from textbooks, web sources (such as a manufacturer‘s web
site), to then be incorporated into a document.

If information is used directly from other sources, those sources need to be

acknowledged, and if there is enough material used directly, copyright permission
needs to be sought.

Creating content

More often, the ideas and words may derive more generally from research, or they may
be related directly to the new system, process or product that has been created and
which needs to be described.

To start your document, you might need to write by hand, to type, to draw, sketch,
record or to take photographs or record video footage. Your work will always start with
research and gathering information. Your goal is to collect answers in many forms.

You may need the help of other people with specialist creative skills, as well as the
technical experts. You may hire technicians, professional writers, professional editors,
graphic artists or photographers as contributors depending on the scope of the
documentation and the best ways of presenting that type of information. In smaller
projects, you might do all the work yourself by being the sole creator of the documents
and ‗wearing several hats‘ as specialist, reviewer, researcher, writer and editor.

Page 72 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 1 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. Give four reasons why technical documents are important.

2. What is expected from IT Technical Writer?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 73 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 2 Translating technical terminology plain English

3.2 Writing skills

The first skill of a writer is being a reader. The skills of all writers begin with ideas and
understanding them. For technical writing that skill involves gathering information, or
having some basis of expertise, and it often involves a combination of both. Writing
techniques or skills then help relate that information clearly and simply to others.

The basics of writing skills, discussed below, can be grouped as follows.

Preparing to write your document

 Plan your document and create an outline

 Know you audience

 Be prepared with references and non-text components

 Begin a first draft.

Using plain English

 Use everyday language

 Use technical words appropriate to the audience

 Use proprietary names and acronyms with care

 Use short and simple sentences, brief paragraphs and lists

 Use active rather than passive voice

 Avoid jargon

 Choose concrete rather than abstract words.

Page 74 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Preparing to write your document

Planning

First, make sure you are clear about what you need to say in this technical document
and why you are writing it. You should have documents that tell you what the document
specifications are and what the user‘s need.

You will also have a template that will help you format the document. You need not
about exact formatting until you‘ve finished writing, but the heading hierarchy and other
features in the template can help you to keep focussed and to structure the document.

The fastest way to write is to start with an outline. It‘s like a shopping list of what you
have to tell the reader. The topics in the outline will become the main points of
paragraphs. It is easier to organise an outline than a whole document. It is much easier
to re-organise a document at the outline stage by moving phrases around, rather than
move entire chapters and sections around after the document is finished.

Know your audience

Who are you writing for? Knowing your audience is important as it helps you choose the
right language and level of detail. Adapt your document‘s content to the knowledge and
interest levels of the audience.

If you haven‘t done so already, talk to some people who might use the document. Ask
them what they need.

Be prepared with references and non-text components

List any references to information in other documents before you write the content. This
allows you to put references into the text as you type your document. This may sound
like a minor point, but it will save you time.

At this point, review the outline you‘ve made for your content and determine the
diagrams, tables, and other non-text devices that can or should be used to add meaning
to the information. The old saying, ‗A picture is worth a thousand words‘ is true. If you

Page 75 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 have your figures, charts, and tables ready, it is much easier to ‗let them do the talking‘
and write around them.

Begin a first draft—just do it

Start with the first or second paragraph or section. Once you start to write, keep going.
Try not to stop in the time you have allotted to do it (unless you have to eat or sleep of
course). Don‘t start with the title page; it is best to save this for last.

It is easier to write without worrying about corrections during the first draft. This allows
you to maintain focus of the topic.

Using plain English

The best advice for writing technical documents is to write clearly, in plain English.
Good writing, whether technical or general, presents information in a clear style.

Plain English for technical writing is that which can be read, understood and acted upon
on the first reading. Plain English needs good design and layout as well as good
language, and is suitable for all kinds of technical information. A golden rule is that plain
English should be used in any information that people rely on when they make
decisions.

You may find that one guide for technical writing clearly recommends the use of short
sentences, everyday words and personal pronouns (such as ‗I‘, ‗we‘, and ‗you‘). Another
guide might suggest the use of the third person for technical writing. This is where style
guides make a big difference in ensuring the consistency of your writing. Whatever you
do, do it consistently.

Some general principles follow.

Use everyday language

Your writing will be easier to understand if you use plain, everyday language. This is not
just a matter of replacing long or elaborate words with plain words, as you might rightly
expect readers to understand technical words (discussed next). For text in which

Page 76 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 technical terms occur you can write in the same kind of language you would use if you
were talking directly to the reader. Table 1 has a few examples of expressions
commonly used, with some clearer alternatives.

Table 2.1: Examples of everyday alternatives to phrases

Phrase Alternative

Currently Now
At such times as/ In the event that When/If
Prior to and following Before and after
A significant amount of/ The majority of Many/ Most
Has the capacity to Can

Use technical words appropriate to the audience

The use of technical terms depends on the level of skill of your users. In a manual for
skilled users of a technology, technical jargon can be a short-cut to information. For
those just learning, the same terms might make understanding difficult.

Technical terms can‘t be avoided in technical documents. But the appearance of

technical words doesn‘t mean that the work must be difficult to for users to understand.
Table 2 has examples of acceptable technical terms used in different documents. To
substitute another word could cause confusion.

Table 2.2: Examples of acceptable technical terms

Term Meaning

data rate The speed in bits of data being moved from one place to another.
Generally, it refers to the speed of the flow of data measured in bits
across a network, through an Internet connection, or from a device
such as a disk drive.
Firewall A firewall is used on some networks to provide added security by
blocking access to certain services in the private network from the
rest of the Internet or other networks. A computer firewall (to use an
analogy), operates in the same way that a firewall in a building does
in keeping fire from spreading.
Kernel The kernel is the set of functions that make up an operating system,

Page 77 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 the essential centre. A kernel can be contrasted with a shell, the
outermost part of an operating system that interacts with user
commands. Kernel and shell are terms used more frequently in DOS,
Windows, and UNIX
Nanosecond A measurement of time. There are 1,000,000,000 (a billion)
nanoseconds in a second.
Serial In computer communications, serial refers to one after another.
Serial data transfer is defined as transmitting data one bit at a time,
in a stream across one line. The opposite of serial is parallel, in
which several bits are transmitted concurrently, across several lines.

Three principles to keep in mind when using specialist terms:

 Be aware of your audience‘s level of understanding; don‘t be too complex for

beginners, or too simple for experts.

 Use technical terms consistently; technical words should never have double
meanings.

 Provide clear definitions or explanations of terms your readers may be unfamiliar

with.

Some documents need use many technical terms, acronyms or abbreviations. To

change words that have real meaning for technicians could cause serious errors.

For example, the word fast, as in ‗a fast internet connection‘, is really an abstract word
and misleading in IT texts. Yet ‗fast‘ has very different meanings in medicine (resistant
to), mining (a hard stratum under poorly constructed ground) and painting (colours not
affected by light, heat, or damp). A specialist dictionary is required for learning technical
vocabulary.

Using proprietary names and acronyms with care

A glossary can help remind your reader of meanings. You might also include reference
to an appropriate on-line dictionary (see Resources for web links). Other aids can
include lists of proprietary names and acronyms.

Proprietary names, such as those in Table 3, are the names of products and services
developed and currently owned by one organisation or individual (usually hardware and
Page 78 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 software). Proprietary names cannot be left out of most technical documents and when
there a great number pf them a list can help remind readers what exactly is being
referred to by each name. If the same proprietary name is used by different makers and
both occur in the document, it would need to be spelled out more fully each time (such
as Microsoft Office software and Corel Office software, for instance).

Table 2.3: Some examples of proprietary names

Name What it is

ActiveX Web page controls for forms to design or collect active data (as
opposed to Java applets).
Java An object oriented programming language created by Sun
Microsystems.
Office Microsoft Office; suites of software including word processing
(Word), a spread sheet (Excel), graphics and other options
depending on the particular package. Corel WordPerfect also offers
an office. IBM‘s Lotus does also.

When acronyms are first used they must be explained and spelled out with the acronym
placed in brackets. Table 4 has examples. Note how the terms not being capitalised can
also make them more readable (though the use of capitals will depend on the house
style for your documentation).

Table 2.4: Examples of acronyms

Acronym Meaning

AUP Acceptable use policy(AUP) is a formal set of rules that governs how a
network may be used.
OEM The term original equipment manufacturer (OEM) has come to mean
the companies actually manufacturing or creating computers, as
against those who package and assemble computers to sell them
under a brand name. The term has come to mean unnamed or
unbranded.
OOP Object oriented programming (OEM)is a style of computer
programming which entails building of independent pieces of code
which interact with each other. For example, JAVA and C++ are object
oriented programming languages.
UPS An uninterruptible power supply (UPS) is a standby power source that
provides power to a server or workstation or other device from a
battery in the event of normal AC power failure.

Page 79 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Simple sentences, brief paragraphs and lists

You may need more words to explain something clearly, and it is best to vary the length
of sentences, but when possible write in short sentences. Shorter sentences make
comprehension easier. It is also useful to keep this in mind for writing on the web, where
users scan for information, only reading thoroughly when they print texts (as you may
have done!).

It is also generally best to have only one or two ideas in each sentence. If you need to
also explain a technical term, use a separate sentence, rather than adding another
clause to the sentence. Also avoid convoluted constructions such as double negatives
(‗not unlikely‘ for example).

Have one main topic in each paragraph. This helps makes the ideas easier to read and
understand. Keep in mind what journalists call the ‗inverted pyramid‘ for information. It
can help if the first sentence of a paragraph is like a summary, which is then explained
in the next few sentences. Keep paragraphs brief.

Place long lists in sentences into lists or bullet points under a simple introductory
sentence, with an explanatory sentence to follow, if needed.

Use active rather than passive voice

Technical writers often write in the passive voice.

One change here is having a simple imperative ‗must‘ replace ‗It is of crucial
importance…that‘. Another is having verbs do the work in the sentence (‗provide‘ for
‗provision‘, ‗use‘ for ‗utilisation‘, ‗maintain‘ for ‗maintenance‘). Note that ‗documentation‘,
as used here, is a technical word—if you were to change it to ‗documents‘, the meaning
would be imprecise. Also note that there are times when the passive is the only suitable
construction, especially in some scientific writing.

A passive construction may also cause ambiguity by masking responsibility. For

instance, the first sentence does not say whether an investigation will take place while
the second (active construction) makes it clear that it will.

Page 80 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Avoid jargon

Jargon can be a specialised language that only people in an organisation or specialist

area understand (shop talk), or a form that is slang. Or it can be nonsense where no
one is really sure of the meaning (gobbledygook). Most readers are antagonised by
jargon and technical writers have a poor reputation for using it. Avoid jargon when
possible, especially:

 undefined acronyms and abbreviations

 non-words, such as slang

 abstract words and phrases

Choose concrete rather than abstracts words

What is a device, output or facility? There are times when an abstract term is apt. Yet
when such words are used instead of the concrete or actual object or activity, they can
be so vague they become meaningless. String them together, such as in ‗output device‘
and you have instant jargon where printer may have been better. Table 2.5 has
examples of abstract words for which a more concrete of specific term might be better.

Table 2.5: Abstract words

activities devices inputs

amenities operations structures
facilities aspects factors
processes variables concepts
functions resources output

Page 81 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 2 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. What is Plain English mean?

2. How to avoid jargon?
3. List the basic writing skills? At least 2

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 82 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 3 Applying content format and style

3.3 Editing and proof reading stages

Technical review

A technical review is a team evaluation of relevant technical documents. The technical

review of a piece of writing or any other form of technical documentation should be the
first level of review, since it is a waste of time to work on a document that has incorrect
content.

Technical reviews are most often conducted by users or specialists. A technical review
may also be conducted by technical referees who are experts in the relevant field.
There should also be another review when the document has been through editorial
stages in production, to be sure no new gremlins have found their way into the work.

The review team identifies deviations from specifications and standards, identifies
errors, and may examine alternative solutions. They provide recommendations for
correction of misinterpretations and for omissions by the writers. The technical review is
less formal than the requirements of approval by the client. The technical review
participants often include the author, and experts in the technical content of the product
or service being documented.

Editing stages and tasks

Editing is ideally a distinct task in producing documents, with the writer and reviewer
providing copy to an editor and liaising with that editor to prepare it to be published or
replicated onscreen. Professional editors have a working knowledge of paper-based
and screen-based publishing. Other general areas of knowledge required cover areas
of:

 legal and ethical concerns (including copyright and cultural issues)

 design, typography and formatting

Page 83 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  technology relevant to editing practice
 reproduction (including print production and web site and document
maintenance).

Correction and editing take place a number of times when preparing a technical
document. Editing stages can also depend on the extent of editorial intervention which
is thought (and agreed to be) appropriate to a particular publication project. Once
guidelines are set for the document (in the design phase) stages will often run as in
Table 3.1.

The focus of editing tasks

Structural integrity

In a longer document, the editor (and later, the Elements

proofreader) checks the placement and integrity  Cover
of any key features or elements, such as those  Title page
in the list opposite.  Copyright or imprint page
In the substantive editing stage the editor  Acknowledgements
assesses the document to make sure that it  Table of contents
accomplishes what it should, and that all the  List of tables and figures or both
necessary information and elements are  Abstract or executive summary
supplied.  Preface
The list opposite is a likely order of pages for  Glossary
print materials, while depending on the  Page numbers
document, the exact order and the number of  Headers and footers
elements will be chosen to suit content. Some  Graphics
similar elements might exist in onscreen  Section dividers/tabs
versions, where preliminary pages will be home  Electronic links
pages linked to other screens.
 Appendixes
Page references in the various sections and for
 Attachments
the table of contents would also be inserted,
 References/bibliography
checked and corrected by the editor, and then
 Works cited
checked again by a proof-reader. The editor
 Index

Page 84 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 would spot check page references in the index
for accuracy, once it is available.

With on-screen publications the editor would help also test elements for functionality
and accuracy such as:

 links

 form fields

 feedback items and provisions

 exit sequences

 pop-up boxes

 downloading and opening of files

 metadata coverage and terminology.

Content and style

The editor makes and suggests changes and amendment to help ensure that:

 the document provides complete information for the work

 the information is appropriate

 the content is designed to help the reader understand and find what is needed.

 the order of information is suitable, that is, it is consistently logical or

chronological

 the flow of information helps readers to understand

 the information is well structured with signposts, graphical symbols, and heading
styles.

The editor also needs to keep in mind a range of style issues, including that:

 the content provided follows the style sheet or guide (if available)

 the writer‘s tone matches the skill of users

Page 85 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  technical words are concrete and accurate

 there is no cultural or gender bias

 any technical terms are appropriate

 the writer uses predominately active voice (except for scientific reports)

 the work has an appropriate point of view (personal when possible)

 grammar and punctuation follow the style for technical documentation

 spelling and capitalisation are correct and consistent (be alert to the damage a
computer spell-check system can do to meaning)

 bulleted and numbered lists are formatted correctly.

Proofreading

Proofreading is a quality control exercise for documents and not a substitute for copy
editing.

With larger technical documents, or with projects that have taken a long time, a
separate proofreader may be employed for the job. A fresh view of the document often
helps as the author and editor may have become so familiar with the documents that
they fail to notice remaining errors and inconsistencies.

Often, however, as is clear in the description of tasks above, the editor‘s scope of work
includes proofreading.

The tasks of proofreading check and ensure:

 Verification of copy (checking against previous copies and checking typeset

proofs).

 Integrity checks (of elements described above and also of cover, dust-jacket
material, spine copy, preliminary and homepages, copyright and publication
information, and contact details)

 Spelling and punctuation errors

Page 86 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  Conformity with style specifications (with an editing style sheet and
organisational style guides)

 Conformity with design specifications (heading hierarchies, running heads and

footers, buttons and scroll-overs and labels, fonts, alignment and spacing, page
or screen layout.

 Sequences, cross references and links (including checking all references to

tables, etc, proofread the index, spot check cross references, spot check
functionality of links and page display)

 Layout (including page and screen breaks, word breaks at the ends of lines or
pages, placement of tables and captions, etc).

If a proofreader has been employed, any corrections, errors or inconsistencies found

are marked-up to be referred to the editor to review.

The author and the editor are responsible for careful review and accuracy of all facts,
dates, spellings and corrections. If a proofreader marks up changes for the typesetter to
take them in, a copy should be sent back to the author for approval, showing where the
changes have been made.

Proofreading tips, peer editing and computer tools

Focus tips

For smaller documents and when a professional proofreader cannot be used, the
following proofreading tricks can help find mistakes.

 Read for only one kind of error at a time. If you try to identify and revise too many
things at once, you risk losing focus, and your proofreading will be less effective.
For the less-experienced, it‘s easier to catch grammar errors if you aren‘t
checking punctuation and spelling at the same time. Some of the techniques that
work well for spotting one kind of mistake won‘t catch others.

 Read slowly, and read every word. It‘s OK for your lips to move when you are
checking for errors. Before the age of electronic files, documents copies or

Page 87 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 galleys from printers were proofed by one person reading out the text and all
punctuation while the other person checked the other copy. Try reading out loud,
which forces you to say each word and also lets you hear how the words sound
together. When you read silently or too quickly you may skip over errors or make
unconscious corrections.

 Separate text into individual sentences. This is another technique to help you to
read every sentence carefully. Simply press the return key after every period so
that every line begins a new sentence. Look for grammar, punctuation, or
spelling errors.

 If you‘re working with a printed copy, use an opaque object like a ruler or a piece
of paper to isolate the line you‘re working on.

Peer review and editing

When managers decide that people in their department should be responsible for
editing their own documents, quality control can become a problem, with errors missed
and standards overlooked.

Peer editing is one way of compensating when there is not a distinct editorial role for
staff. This works by having people in your department edit the work of their colleagues.
From a point of view of technical understanding, people in the same department should
also be able to review draft documents and spot errors; they should know the subject
matter fairly well, even if they see the work with different skills. A work culture where
group members collaborate to produce quality documentation is important for peer
editing to work well.

Peer editing and review can work by having:

 individual editing

 group editing responsibilities (for longer documents).

Page 88 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 With group editing, all team members review draft documents. Then they meet as a
team to discuss any problems they find. (A good manager will prevent the group
reviews from turning into a ‗hunt the writer‘ session.)

Computers spell checks, grammar checks and document control

Spell checkers

Most word processing programs have tools to help in editing and correcting documents.
The spell checker feature is well known. It is also well known for its ability to replace
sensible words with non-sense words, when a writer isn‘t paying attention to the screen,
and the document isn‘t checked carefully. Some of these are words that are in fact
correct but in the wrong place, such as the word ‗from‘ instead of ‗form‘, ‗of‘ instead of
‗or‘. A good practice when using spellcheckers is to check for instances of these
particular words to make sure they are correct in each use.

Grammar checkers

Grammar checkers can be useful to a degree, for pointing out passive constructions or
fragments, and for showing errors in such things as singular and plural forms and when
subjects and verbs don‘t agree. Yet with technical documents, especially scientific
documents, you would be best advised to use your own judgement—sole reliance on
such tools can overlook and even introduce errors.

Document control and revisions

For document control Microsoft Word uses a feature called Version, which attaches a
version number to each new draft of a document. This feature is found in the File menu.

Microsoft Word is also one of many word processing packages that allow two versions
of a document to be read and compared side-by-side, on the screen, and when
changes are made by several editors, they can be merged into one document. This
utility is called Compare and Merge Documents, and can be found in the Tools menu
(though you are well advised to save a copy for all documents before doing this).

Page 89 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Tools to monitor revisions also exist in the word processing packages. When
corrections have been made in Microsoft Word by a reviewer or editor, the author can
see what has been deleted and what has been added or changed, by coloured lines in
the copy. This feature is called Track Changes, and can also be found in the Tools
menu.

A feature for adding notes and comments is also commonly used for reviewing
documents and can be used for editor‘s queries.

In current versions of Adobe Acrobat, PDF files can also be marked up on-screen to
make changes at a proof stage for documents that have already been typeset or
converted to HTML.

Page 90 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 3 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. Where would you find metadata about a technical document on a web page?
2. Name four other professions, in addition to technical writers, that may be
involved in producing technical documentation.
3. What are three principles to keep in mind when using specialist technical terms?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 91 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LG #46 LO #4 - Evaluate and edit documentation
Instruction sheet
This learning guide is developed to provide you the necessary information regarding the
following content coverage and topics:
 Submitting technical documentation
 Gathering and analyzing feedback
 Incorporating alterations into the technical documentation
 Editing technical documentation

This guide will also assist you to attain the learning outcomes stated in the cover page.
Specifically, upon completion of this learning guide, you will be able to:
 Submit technical documentation
 Gather and analyzing feedback
 Incorporate alterations into the technical documentation
 Edit technical documentation
Learning Instructions:
Read the specific objectives of this Learning Guide.

1. Follow the instructions described below.

2. Read the information written in the ―Information Sheets‖. Try to understand what
are being discussed. Ask your trainer for assistance if you have hard time
understanding them.
3. Accomplish the ―Self-checks‖ which are placed following all information sheets.
4. Ask from your trainer the key to correction (key answers) or you can request your
trainer to correct your work.
5. If your performance is satisfactory proceed to the next learning guide,
6. If your performance is unsatisfactory, see your trainer for further instructions

Page 92 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 1 Submitting technical documentation

4.1 Communicating the process

After all the stages of design and production, you still need to be well prepared when
seeking final sign-off on technical documentation. In addition to being on top of the
subject and purpose of documentation, you may need to know:

 the business the organisation operates in

 your organisation‘s ways of doing business.

While the purposes and procedures for sign-off may be clear, a client‘s sign-off and
agreeing to accept the hand-over of a finished product should not be seen as a simple
formality. Many projects stumble and fail at this last hurdle, because approval was a
process that was taken for granted.

You should sometimes be prepared for a less-than-smooth ride when you want work
approved even after all the elements of documentation have been thoroughly double-
checked.

A novice may request sign-off without care and planning. A report is sent to a client,
attached to an email, asking for agreement, or sent by a messenger or courier. This
could turn out to be a bad move. The request could sit in the client‘s ‗too hard basket‘
for days. When the manager gets around to reading the request, there may be
questions about details, so it goes back into the ‗pending‘ tray.

Asking for a manager‘s approval for a document is very basic and often taken for
granted beginners may forget to ask for signature on the sign-off form directly,
personally and clearly.

One approach can be to ask for a meeting, for handover, not for sign-off. Have your
team of technical experts on call, to present the technical details, in simple language.
Include your final checklists for scrutiny.

Page 93 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 More simply, phone the client first, or see them, and tell them the relevant draft of
documentation (or drafts of an information set) is being sent to them and ask if they
could respond soon as possible. Their reply and signature is often much quicker if you
do it this way.

Page 94 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 1 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. Who is giving approval for the draft document?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 95 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 2 Gathering and analyzing feedback

4.2 Strategies for gaining sign-off

How sign-off works

Client sign-off can occur for various points in the design and production of
documentation. Sign-off makes certain people accountable for the completion of various
stages. Those with authority to sign can be accountable for the cost of documentation
and its quality and integrity, or both. It is the client who decides when the work is
completed and functional.

Acceptance is based upon the success criteria defined in the very early initiating and
planning stages of the work. Sign-off therefore also helps to define and structure the
stages of development and production.

When documentation is submitted to be signed off, changes are often needed in

response to feedback before sign off can occur. The phases or steps can be much like
those in project management or systems development. As the point of each ‗deliverable‘
is reached, the client or a subject expert needs to review and approve the work to this
stage. This feedback gives all participants the chance to correct flaws.

Controlling the development of technical documents is also very similar to project

management. Clear, manageable and efficient procedures must be in place to handle
version control, change control, document updating, and distribution as the work
progresses.

The final sign-off on technical documentation is often a crucial stage in the completion
of IT projects. When documentation is signed off it ensures that:

 the original specifications and requirements criteria for documentation are being
met

 there is formal acceptance, in writing, that the client, project manager or sponsor
have accepted the documents are complete and accurate

Page 96 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  work by outside contractors or suppliers is formally accepted (and paid for)

 documents are authorised for final production and distribution.

The final decision to sign-off comes from the client. But the client will often need to listen
to other people within an organization, including those who steer the organization, who
pay the bills, the users and any experts who have contributed to documentation.

Each of the following stakeholders, for instance, may approve the design and planned
use of technical documents.

 Business units may have requirements that depend on the content and
accessibility of all documentation.

 Administration may need to ensure that documentation management will comply

with external and internal constraints, such as ISO 9000 Quality Standards.

 The IT group may be obliged to support and maintain digital documentation,

storage, hardware and programs, communications, and compatibility within
existing systems.

 Audit and accounting staff may need to ensure that documentation

accommodates organisational financial policies and obligations.

 Legal counsel may review documents for legal consequences and contractual
implications.

You can see from this list that sign-off on technical documentation can involve a broad
team of people. Methods are needed to manage the approval of a range of
stakeholders.

Sign-off times

For technical documents, signed client approval and review by other stakeholders are
generally required at the outset of planning, where the project is approved, and again at
the end of the project.

Page 97 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 However, at each deliverable stage, especially for the end of each draft, a technical
expert might review and endorse the writer‘s or graphic artist‘s work. Confirmation is
also needed that recommended changes are included in the next draft.

By the final draft, expert review of the document is needed. It is also wise at this stage
to test the document with a review by eventual users. These are the people to whom
clear usability of the document is essential. Then, when agreement is reached or the
work is ready to be passed from developer to client, someone in authority needs to sign
on the dotted line for reproduction.

Procedures for sign-off

Most organizations will have procedures for documentation sign-off that are similar to
the procedures followed to approve projects. Table 2.1, outlines stages at which the
plans for documents, or the documents themselves, might be subject to formal
approval.

Table 2.1: Some likely sign-off points for technical documentation

Phase Activity Related approvals

Planning Project initiation Feasibility report approval

Content The determination of the Approval of scope document and publishing schedule
specification scope of client requirements or timeline
and the scope of work
Implementation Development completion Approval of technical review
Production and Design completions Client validation and approval of technical
evaluation documentation structure
Completion of documentation Review and user testing approval
Approval of printers proofs or web site screens, or
both

Approval checklists for paper-based and onscreen documentation

For both print and onscreen documents a range of elements may need to be checked
before approval to publish them is sought.

Page 98 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 A checklist prior to sign-off might include each individual component as in Table 2.2 for
print materials, where final checks before going to print would include making sure
document design styles have been applied correctly.

Table 2.2: Sign-off checklist for print materials—elements

Cover Page numbers

Title page Headers and footers

Copyright or imprint page Graphics

(ISBN or ISSN or both,
copyright statement)

Acknowledgements Section dividers/tabs

Table of contents Electronic links
List of tables and figures or Appendixes
both
Abstract or executive summary Attachments

Preface References/bibliography

Glossary Works cited

Page numbers Index

A summary checklist for onscreen documents is more elaborate, since the onscreen
presentation requires content that may not have yet been checked in an editing process
(as content will have been). A useful general pre-approval checklist is shown in Table
2.3 on the next page.

Page 99 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Table 2.3: Pre-approval checklist for electronic documents

Identification details

Are the document owner (or sponsor), title and author identified?
Are standard document identifiers attached: ISBN or ISSN or both,
library metadata, copyright statement?

Are acknowledgements included (if needed)?

Are references made to any related or associated print documentation?
Is the date of publication (and the most recent revision) shown?

Have contact details and any relevant feedback links been given?
Legal aspects

Has a disclaimer statement been included (if needed)?

Design and navigation

Does the design reflect the corporate or in-house image or identity?

Do pages and screens suit screen characteristics (such as size, shape
and resolution)?

Are there the kinds of search facilities users need (topics index, key
word searching, etc)?
Do all color images meet the web 216 color standard for the Internet?

Where relevant, are the navigation elements on every screen linked to

any larger information structure (such as a home page or host web
site)?
Are there clear pathways within the documentation and is each page
suitable linked (that is, no dead end pages)?
Access and transmission

Are the file formats appropriate?

Have bandwidth, access speeds, file sizes and browser compatibility
been taken into account.
Does it meet W3C guidelines for web access?
Testing and evaluation

Are readers able to find the documentation using search engines?

Is it easily opened and printed (if necessary)?

Do navigation features work correctly?

Page 100 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Will the screen display match expectations?

Approval methods

Methods used to gain sign-off might include consent forms, circulation lists or some
form of electronic approval.
Consent forms
A sign-off consent form might sensibly include the following elements:
 A title, saying what it is that you want the client or executive to approve (a design
plan, a form, a template etc).
 A reference to the role this document will play in an over-all project or system.
 A description of what is being agreed to including a description of what has been
reviewed.
 An explanation of how any later changes to the documentation may be handled
after the form has been signed.
 In cases where work has been done under contract, especially for an agreed-to
deliverable, permission to issue an invoice might also be included.
 Space for signing and dating.

Circulation list

Sign-off of smaller technical documents may be served with a distribution list. The work
to be approved might be circulated to a number of executives and experts, along with
approval checklists such as those in Tables 2 and 3 above, or checklists that are
specific to particular people‘s expertise.

Each person on the circulation list is required to review the work, add comments and
forward the document to the next person on the list. (It is essential that you keep track
of the progress of the documents). When the comments and signatures are all returned,
and you have incorporated valid changes into the master documents, you will need to
re-circulate the documents, so contributors can see what changes have been made or
incorporated. (For print documents, Microsoft Word is one of many applications that
Page 101 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 have features to help with the group review of documents in this way.) Table 2.4 is an
example of a simple circulation checklist.

Table 2.4: Sample circulation list

Name Position Signature Date

Alex Project manager

Tigist IT Manager
Feyisa Legal
Senait Administration
Jemal File Librarian
Gada Corporate Secretary

Gedion Technical writer

Electronic approvals

A document can be reviewed, agreed with and approved on-screen. A typical example
is an end-user-license agreement (ULA), where terms of the agreement are displayed,
and nothing more can happen until the user clicks ‗I agree‘ to confirm a contract with the
software developer.

Similarly approval of technical documents can be done using secure technology, such
as digital certificates, to ensure that a signature is authentic and not copied by another
person from another source. (A signature that has been scanned from a paper
document and included in an electronic document is not a legal signature).

Page 102 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 2 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. If you are able to consider an organization you work for, can you identify your
organization‘s procedures for approving technical documents?
2. If you are able to consider an organization you work for, of a workplace to which
you have access, who are the appropriate people in your organization who are
deemed competent to review technical documents for completeness and
accuracy before sign-off?
3. Briefly list some of the methods you would use to submit technical documentation
to experts for review and verification.
4. Name a software application has features to help you gather, analyze and
integrate feedback from reviewers of documents.

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 103 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 3 Incorporating alterations into the technical
documentation

4.3 Technical Writing Is Changing With The Times

Change and obsolescence are a constant reality of our lives. In most spheres of life, we
can anticipate and prepare ourselves for the changes that lay ahead. But when it comes
to technology, the change is so sudden and disruptive, that we are swept aside before
we realize what hit us! A number of technology companies can be cited that were
caught unawares in the technology.

Ever wondered how some prominent and successful products suddenly vanish from the
market or are forced to undergo major changes, due to seemingly unrelated
alternatives? For instance, the hapless bed-side alarm clock simply vanished at the
advent of mobile phones. Or the humble post card became a vintage souvenir after
people discovered the joy of emailing!

Technical writing has always been an integral part of the product lifecycle. Before the
digital revolution, technical documentation was the only way to reach out to the target
user, at any lifecycle phase.

What is changing constantly are the subject areas covered (due to newer products in
new technology spaces), tools used for drafting technical documents, media used to
publish these documents and increased video content against written content.

Page 104 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 SubjectAreas:

Technical writers are essentially people who are familiar with the product and the
underlying function it provides to the customer. In the traditional sense, the technical
writing was associated with electrical / electronic equipment as consumer goods,
defense equipment, infrastructure projects, etc. For instance, the technical
documentation produced by NASA is supposedly around 4 million official records! They
have their own strict documentation style guide and hundreds of people employed in
their documentation department.

But technical writers need to brace themselves for new emerging technologies
constantly. Medical electronics, process automation, cloud-based online products,
complex financial instruments these are some of the current flavors of the market
space. Those technical writers, who successfully manage the leap, thrive, while the rest
struggle to survive.

New age tools and trends in technical writing:

Advertorials – These are articles written in print/digital media on technical subjects by

subject matter experts. But the written content would show an inclination to promote a

Page 105 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 certain company or a specific product. Such documentation serves dual purposes
educating and inducing the public!

Digital content for hand-held devices – Transition from printed material to digital
content for PCs and laptops signified a paradigm shift in technical writing. The next step
is moving to concise, easy to grasp content presented on miniature, portable
smartphone devices.

Cloud storage of technical manuals – Technical documents are no longer bundled

with the product alone. Your washing machine is several years old and you have
misplaced the user manual? Never mind, you can access the manual online anytime,
anywhere.

IT based authoring tools – In the print era, technical writing encompassed several
sub-roles of copy editors, proof-readers, stenographers, typists, publishers, etc. But
today these roles are replaced by powerful software products, some of them are

 Word processors (Microsoft Word, Open Office)

 Authoring and publishing tools (Microsoft Visio, Abode Frame Maker, Word Press)

 Image editors (Adobe Photoshop, GIMP)

 Web development tools (Dream Weaver).

Associated roles in tech writing:

Is there a case of the traditional technical writer to fret? Not if he or she can morph into
one of these new age role associated with technical documentation.

 As an illustrator, you can use graphic sketches and picture-stories to condense

written content into visual form.
 A layout designer can plan the web page layout of blogs and web pages.
 Script writers can use roles plays to elaborate on a product‘s user functions.
 User experience testers can act as proxy end users and simulate actual usage to
discover human usage behavior patterns and ease of use.

Page 106 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  Video content creators can churn out product usage videos using live demos,
animation content.

Self-Check 3 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. How Technical Writing Is Changing With The Times?

2. What aspect of technical writing does change with time?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 107 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Information Sheet 4 Editing technical documentation

4.4 Effective Editing of Technical Documents

A highly polished document reflects the professional image of an organization.

Technical editing plays a significant role in developing technical documents, such as
user manuals, procedure manuals, software guides, organizational brochures, and so
on. Think of editing as the big picture of process. It is a crucial part of all technical
writing projects. However, I have multiple levels of technical editing, which makes my
task challenging.

Level 1 Spec Editing

A Spec edit is a detailed edit that includes format editing and readability checks. Editors
determine whether documents satisfy all the macro requirements specified in the
documentation plan.

 Format Check Technical editors make sure that a document contains correct
chapters, sections, page numbers, and a glossary, as required. A technical editor
also determines whether the document includes a table of content, index, list of
figures and tables, and copyright information.

 Readability Check Technical editors determine whether the language and

readability level are appropriate for the specific audience.

Level 2 Style Editing

Technical Editors determine whether the writer has used the abbreviations, acronyms,
and stylistic conventions specified in corporate or client guidelines.

 Spell out acronyms when they appear in the document for the first time.

 Eliminate jargon.

 Verify that figures and table captions are in the corporate style.

 Verify that font family, font size, and color palette is correct.

 Verify that the language is free of gender bias.

Page 108 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Level 3 Comprehensibility Editing
This type of editing answers a question: Is the content in the document used in a logical,
easy-to-understand sequence? Technical Editors focus on the logical flow of
information. They can help a writer determine whether the document meets the
standards for the way words form phrases, phrases form sentences, sentences form
paragraphs, and paragraphs compose sections.

Level 4 Copy Editing

Technical editors check grammatical errors as well as typos in the technical documents.
Editors also check whether individual sentences are well formed. In a scientific or a
technical document, write sentences in a short and straight-forward manner. Technical
editors correct sentences that are too long for the reader to comprehend on first
reading. Long sentences contain complex clauses that can confuse readers who are
trying to understand technical information.
Technical editing affects the style of writing in technical communications. Technical
editors can use these tips about types of edits to produce professional technical
documents. Because these stylistic enhancements allow readers to understand the
content more easily, the changes also have an impact on the quality of technical
content.

Page 109 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Self-Check 4 Written Test

Directions: Answer all the questions listed below.

I. Write appropriate answer for the following question.

1. What kinds of editing Level 2 Style include?

2. What kinds of editing Level 4Copy include?

Note: Satisfactory 100%

You can ask your teacher for the copy of the correct answers.

Name: ___________________ Date: ____________ Score: ____________

Page 110 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Reference
State of New South Wales, Department of Education and Training 2006
https://medium.com/@kesiparker/elements-of-technical-documents-396f0805eae8

https://smartbear.com/learn/code-review/what-technical-documents-should-you-review/

https://www.teamgantt.com/blog/project-scope-document

https://www.techrepublic.com/article/tips-for-managing-the-technical-documentation-
tech-review/

https://stc-techedit.org/tiki-index.php?page=Effective+Editing+of+Technical+Documents
https://academy.whatfix.com/how-technical-writing-is-changing-with-the-times/

Page 111 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 AKNOWLEDGEMENT

We wish to extend thanks and appreciation to the many representatives of TVET

instructors and respective industry experts who donated their time and expertise to the
development of this TTLM.

We would like also to express our appreciation to the TVET instructors and respective
industry experts of Regional TVET Bureaus, TVET College/ Institutes, BEAR II Project,
Bishoftu Management Institute Center, UNESCO and Federal Technical and Vocational
Education and Training Agency (FTVET) who made the development of this curriculum
with required standards and quality possible.

This TTLM developed on December 2020 at Bishoftu Management Institute Center(Bin

International Hotel).

The trainers who developed the TTLM

No Name Qual Educational Region Profession E-mail Mobile
. background /Job title
1 AyansaErgiba A Msc. ICT mgt Oromia Instructor aergiba@gmail.com 0917851343
3 EjiguBirhanu B Msc. ICT mgt Oromia Instructor ejigubiranu2011@gmail.com 0906566892
2 EndaleLema B Msc. ICT mgt Oromia Instructor endhiywet@gmai.com 0913292212
4 KeresaGadisa B Msc. ICT mgt Oromia Instructor keresag2010@gmail.com 0920420664
5 MeseretTezera A Msc. ICT mgt Oromia Instructor YafetMes@gmail.com 0911751285

Page 112 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 Answer Key Module Title: Creating Technical Documentation

LO #1- Identify and analyze documentation needs

Self-Check1 Written Test

Part 1: Choose the best answer

1. E
2. C
3. False. The design of any technical document should allow for control of the
quality of the work and for future changes. Research shows the most frequently
cited reason for failure to earn quality standard certification for technical work is
inadequate document control.

Part 2: Write appropriate answer for the following question.

1. Technical documentation is very specific in its purpose; in the IT industry it is for

use by specialists who develop and maintain the software and hardware, for
instance. It contains technical information about the system, including software
and hardware components. Examples of this type of documentation include
forms, reports, product specifications and operating procedure manuals.

User documentation is for the users or operators of the application who carry out
the business functions of the organization, such as data entry operators, finance
officers, executives and managers. Examples of this type of documentation are
simple manuals aimed at users, training manuals, online help and tutorials, and
policy documents and licensing agreements.

Page 113 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LO #1- Identify and analyze documentation needs
Self-Check 2 Written Test

Part 1: Write appropriate answer for the following question.

1. Managers, technical staff and operators all use technical documentation.

2. Some questions that you may ask to gather information about your organization‘s
technical documentation requirements many include:
 What documents does the organization need?
 What documents exist that aren‘t necessary?
 What are the documents used for?
 Who uses them?
 What information should they include?
 What format will they have?
 What style will be used?
3. Techniques that you can use to find out your requirements are:
 interviews
 checklists and templates
 workshops and use cases
4. If you create a template with a place for version information on documents you may
be better able to consistently ensure your documentation has the necessary
information included.
5. Necessary, Supportable, Unambiguous, Complete, Dependable, Concise,
Acknowledgement & Identified.

Page 114 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LO #1- Identify and analyze documentation needs
Self-Check 3 Written Test

Part 1: Write appropriate answer for the following question.

1. Technical standards enable you and the project team to:

 facilitate communication between IT specialists

 feel confident about quality assurance

 develop product consistent with other specialists

 trace and correct errors

 work efficiently

 have a permanent record of the system

 solve problems with the system

 Provide information for new employees.

2. Some examples of technical documentation that you may find in an IT section

could include:
 network connection diagrams
 hardware specifications
 service level agreement
 password security policies
 request for proposal documents
 frequently asked questions.
3. There are many tools available to you such as word processing software,
drawing software and desktop publishing software that can provide uniformity
and consistency.
4. Three advantages of computer-based documentation are:
 it can be flexible
 allows interaction
 easy to update.
Page 115 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LO #1- Identify and analyze documentation needs
Self-Check 4 Written Test

Part 1: Choose the best answer

1. A
2. B
3. D
4. D

LO #1- Identify and analyze documentation needs

Self-Check 5 Written Test

Part 1: Write appropriate answer for the following question.

1. Project constraints are limiting factors for your project that can impact quality,
delivery, and overall project success.
2. This is the most basic step to creating a helpful scope statement. Before getting
into basic organization, you have to be fully aware of what is being asked of you.
What‘s expected in terms of tangible product, and how does this expectation fit
into the larger scope of the project? Having a basic understanding of what is
being asked of you on a production level will help you assess how to move
forward with assigning roles and setting deadlines.
3. As counterintuitive as it might seem, it‘s often helpful to know what‘s not
expected of you on a given project. The clearer the boundaries are the better. In
order to avoid clogging up your project scope document with a lot of excess,
intangible goals and deliverables, keep it simple. Ask what‘s expected of you,
and what‘s not expected of you, so you can avoid burdening yourself with more
work than is needed or desired by the client, or even helpful to the project at
hand.
Page 116 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LO #2- Design documentation
Self-Check 1 Written Test

Part 1: Write appropriate answer for the following question.

1. You might be designing documents to:

 develop new software applications
 control a major project
 manufacture new products
 maintain equipment
 explain operating policies and procedures.
2. Answers will vary. A sample answer is that a technical document is an object that is
necessary to operate, maintain, repair, support or dispose of a system or equipment
throughout its life. It may be in paper or electronic format, and in a range of media.
3. The body matter of a document includes the chapters or sections of the document.
Each chapter or section should start with a heading and a summary of the other
main headings in the section. In online documents cross references between
sections are made with hyperlinks. Appendices such as tables, or raw data or other
sets of technical information that help the reader understand complex information
can also be placed in the main section of a longer technical document.

Page 117 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LO #2- Design documentation
Self-Check 2 Written Test

Part 1: Write appropriate answer for the following question.

1. A style guide is a reference document used in an organization to guide the writing

style and presentation of documentation, and to ensure consistency and a common
corporate image across a range of documents.
2. A style guide specifies details of writing and presentation style, often for a particular
organization (a house style), and includes guidance in such matters as punctuation,
capitalization, and rules for spelling and usage, as well as the ways in which
materials are to be produced.
Style sheets for documents accompany individual documents and are a record of
all decisions made for that document.
A style sheet can also be a set of formatting commands for a template that are
kept separate from the actual content being formatted, such as with Cascading
Style Sheets (CSS), a feature applied to web pages to ensure consistency of
features on a web site.

LO #2- Design documentation

Self-Check 3 Written Test

Part 1: Write appropriate answer for the following question.

1. By Build accountability into the document review process, Raise the accuracy bar
for technical writers, Set priorities for busy, but key, developers
2. The company or Organizationitself&The Customers

Page 118 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LO #2- Design documentation
Self-Check 4 Written Test

Part 1: Write appropriate answer for the following question.

1. Copyright comes into effect as soon as something that can be protected is

created and ‗fixed‘ in some way, for example, on paper, on film, via sound
recording, or as an electronic record on the Internet. Copyright protection is
immediate and automatic once a copyright work is created. The work is then
generally protected by copyright law for the life of the author and a further 70
years.
2. copyfree is used informally when on object is free from copyright protections, and
may be copied, changed or distributed freely. A copyleft license uses copyright
law to ensure that every person who receives a copy or derived version of a work,
can use, modify, and also redistribute both the work and derived versions of the
work

LO #2- Design documentation

Self-Check 5 Written Test

Part 1: Choose the best answer.

1. E

2. C

3. E

Page 119 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LO #2- Design documentation
Self-Check 6 Written Test

Part 1: Fill in the blank.

3. General ways of organizing onscreen documents so that they can be searched

and used.
4. Access schemes

Part 2: Write appropriate answer for the following question.

5. A metaphor is a figure of speech that is used to make a comparison between two

things that aren't alike but do have something in common. Unlike a simile, where
two things are compared directly using like or as, a metaphor's comparison is
more indirect, usually made by stating something is something else.

LO #3- Develop documentation

Self-Check 1 Written Test

Part 1: Write appropriate answer for the following question.

1. Reasons why technical documents are important include that they:

 help build, operate, repair or maintain equipment and

systems

 help understand complex technologies, events or practices

 help people to share new technical ideas with others, to

introduce new products, new ways of doing things and new
ways of understanding things

 help people see the technical, financial, or social value of

new ideas

Page 120 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
  record events that have a technical element, such as network
crashes, large loss of data, tests for new equipment, and
unusual events, like a hacker break in.

2. An IT technical writer is any person responsible for writing hardware and

software documentation, online help, technical definitions and technical
product descriptions for publication on paper, or on web sites.

LO #3- Develop documentation

Self-Check 2 Written Test

Part 1: Write appropriate answer for the following question.

1. Plain English for technical writing is that which can be read, understood and acted
upon on the first reading.

2. Use when possible

 undefined acronyms and abbreviations

 non-words, such as slang

 abstract words and phrases

3. Preparing to write your document

 Plan your document and create an outline

 Know you audience

 Be prepared with references and non-text components

 Begin a first draft.

Page 121 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LO #3- Develop documentation
Self-Check 3 Written Test

Part 1: Write appropriate answer for the following question.

1. Metadata provides information about the content, quality, condition, and other
characteristics of data: on a web page, the metadata is found in the Head section of
the HTML code.
2. Skill areas used to produce technical documentation could include (among many
others): editors, graphic designers, videographers, multimedia artists, web and
intranet information designers, translators.
3. Three principles to keep in mind when using specialist terms are to:

 Be aware of your audience‘s level of understanding; don‘t be too

complex for beginners, or too simple for experts.

 Use technical terms consistently; technical words should never

have double meanings.

 Provide clear definitions or explanations of terms your readers

may be unfamiliar with.

Page 122 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LO #3- Evaluate and edit documentation
Self-Check 1 Written Test

Part 1: Write appropriate answer for the following question.

1. manager‘s

LO #3- Evaluate and edit documentation

Self-Check 2 Written Test

Part 1: Write appropriate answer for the following question.

1. Determine requirements, Plan documentation, Design documentation, Write

documentation, Review documentation, Update documentation, Sign-off of
documentation by relevant parties
2. The author of the document, subject experts, testers, the requester of the
document (the client).
3. There are several methods for submitting documentation to experts for review.
The method used would depend on the size of the organization and could
include.
 A consent form that includes the details of all the people that would be
required to approve the documentation
 A circulation list that could be used for a small document that needs
review
 An electronic approval method where the document is approved online
by the reviewers could also be used.
4. Microsoft Word and many other proprietary software applications have features
to help you gather, analyze and integrate feedback from reviewers of documents.
The features such as track changes and comments are very useful in this regard.
Spreadsheets, such as those produced by Microsoft Excel can also be used to
manage and track the process of review.

Page 123 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020
 LO #3- Evaluate and edit documentation
Self-Check 3 Written Test

Part 1: Write appropriate answer for the following question.

1. When it comes to technology, the change is so sudden and disruptive, that we
are swept aside before we realize what hit us!
2. What is changing constantly are the subject areas covered (due to newer
products in new technology spaces), tools used for drafting technical documents,
media used to publish these documents and increased video content against
written content.

LO #3- Evaluate and edit documentation

Self-Check 4 Written Test

Part 1: Write appropriate answer for the following question.

1. Spell out acronyms when they appear in the document for the first time, Eliminate
jargon, Verify that figures and table captions are in the corporate style, Verify that
font family, font size, and color palette is correct & Verify that the language is free
of gender bias.
2. It checks grammatical errors as well as typos in the technical documents. Editors
also check whether individual sentences are well formed.

Page 124 of 124 Federal TVET Agency TVET program title-Database Administration Version -1
Author/Copyright Level III December 2020