Web Development and Database

Administration
Level IV.
Based on November 2023, Curriculum Version II

Module Title: Create Technical Documentation

Module code: EIS WDDBA4 M09 1123
Nominal duration: 50Hour

Prepared by: Ministry of Labor and Skill

November 2023
Addis Ababa, Ethiopia
Table of Contents
Acknowledgment ............................................................................................................................ 1

Acronym ......................................................................................................................................... 2

Introduction to the Module ............................................................................................................. 3

Unit One: Documentation needs identification............................................................................... 4

1.1 Identification of documentation requirements ...................................................................... 5

1.2 Interpreting and evaluating documentation requirements..................................................... 7

1.3 industry documentation standards......................................................................................... 8

1.4 Defining and documenting scope of work .......................................................................... 10

1.5 validation and confirmation of the scope of work .............................................................. 12

Self-Check 1.................................................................................................................................. 17

Unit Two: Design documentation ................................................................................................ 18

2.1 Identification information requirements ............................................................................. 19

2.2 Creating document templates .............................................................................................. 21

2.3 System functionality review ............................................................................................... 22

2.5 Validation of technical documentation structure ................................................................ 25

Self-Check 2.................................................................................................................................. 27

Unit Three: Develop documentation ............................................................................................. 29

3.1 Writing technical documentation ........................................................................................ 30

3.2 Translating technical terminology ...................................................................................... 33

3.3 Applying content format and style ...................................................................................... 34

Self-Check 3.................................................................................................................................. 36

Unit Four: Evaluating and edit documentation ............................................................................. 38

4.1 Submitting technical documentation................................................................................... 39

4.2 Gathering and analyzing feedback ...................................................................................... 39

 4.3 Incorporating alternatives to the technical documentation ................................................. 40

4.4 Editing technical documentation......................................................................................... 41

Self-Check 4.................................................................................................................................. 42

References ..................................................................................................................................... 43

Developer’s Profile ....................................................................................................................... 44

Acknowledgment
Ministry of Labor and Skills 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 Teaching, Training and Learning Materials (TTLM).

Page 1 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Acronym
API -------------------------------------------------Application Programming Interface
FAQ ------------------------------------------------Frequently Asked Questions
HTML---------------------------------------------Hypertext Markup Language
ISO -------------------------------------------------International Organization for Standardization
ISTC-----------------------------------------------Institute of Scientific and Technical Communicators
LAP-------------------------------------------------Local Area Plan
PDF-------------------------------------------------Portable Document Format
SOP------------------------------------------------scope of work

Page 2 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Introduction to the Module
This module is designed to meet the industry requirement under the Web Development and
Database Administration occupational standard, particularly for the unit of competency Creating
Technical Documentation. Absolutely done well, technical documentation simplifies complicated
ideas into clear and easy-to-understand guides that even non-experts can understand.

Module covers the units:

 Documentation needs identification

 Design documentation

 Develop documentation

 Evaluating and edit documentation

Learning Objective of the Module

 Identify and analyze documentation needs

 Understand and design documentation
 Develop documentation
 Evaluate and edit documentation

Module Instruction

For effective use this module trainees are expected to follow the following module instruction:

1. Read the information written in each unit

2. Accomplish the Self-checks at the end of each unit
3. Perform Operation Sheets which were provided at the end of units
4. Read the identified reference book for Examples and exercise

Page 3 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Unit One: Documentation needs identification
This learning guide is developed to provide you the necessary information regarding the following
content coverage and topics:
 Identification of documentation requirements
 Interpreting and evaluating documentation requirements
 industry documentation standards
 Defining and documenting scope of work
 Validation and confirmation of 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:
 Understand and Identification of documentation requirements.
 Analyze and interpreting the documentation needs.
 Understand industry documentation standards
 Determine documentation of the scope of work
 Conduct validation and confirmation of the scope of work

Page 4 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
1.1 Identification of documentation requirements
 Basic Concept of 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.

Documentation refers to the process of creating, collecting, and maintaining documents that
provide information, instructions, or evidence. It plays a crucial role in various fields, including
software development, business, education, healthcare, and more. Here are some basic concepts
related to documentation:

 Purpose:
 Communication: Documentation serves as a means of communication,
conveying information to different audiences such as users, developers,
administrators, and stakeholders.
 Reference: It provides a reference point for understanding processes,
procedures, systems, or products.
 Types of Documentation:
 User Documentation: Intended for end-users and includes manuals, guides, FAQs,
and other materials to help users understand and use a product or service.

Page 5 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Technical Documentation: Aimed at developers, system administrators, or other
technical audiences, providing in-depth details about the inner workings of a system
or software.
 Components of Documentation:
 Instructions: Clear and concise step-by-step guidance on how to perform a task or
use a product.
 Descriptions: Detailed explanations of concepts, processes, or components.
 Examples: Illustrative cases or scenarios to demonstrate usage or implementation.
 Visuals: Diagrams, charts, screenshots, or other visual aids to enhance
understanding.
 Technical Documentation
Technical documentation is a type of documentation that provides detailed information about a
technical product, system, or process. It is primarily aimed at a technical audience, including
developers, system administrators, engineers, and other professionals who need in-depth
knowledge to understand, implement, or maintain a technology. Here are key aspects of technical
documentation:
Types of Technical Documentation:
 API Documentation: Describes the Application Programming Interface (API) of
software, detailing how developers can interact with it.
 System Documentation: Provides an overview of the entire system architecture,
components, and their interactions.
 Code Documentation: Includes inline comments within the source code to explain
the logic, functions, and methods.
 Hardware Documentation: Describes the specifications, configurations, and
usage guidelines for hardware components.
 Network Documentation: Details the network architecture, protocols, and
configurations.

Page 6 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  User Manuals for Technical Users: Manuals that provide detailed instructions for
technical users, often in addition to standard user documentation.

 Technical Documentation Content and Structure:

 Overview: A high-level introduction to the product or system, explaining its
purpose and key features.
 Installation: Detailed instructions for installing and setting up the product or
system.
 Configuration: Information about how to configure the system, software, or
hardware for specific requirements.
 Usage Guidelines: Instructions on how to use the product or system effectively,
including command references, workflows, and best practices.
 Troubleshooting: Guidance on identifying and resolving common issues, error
messages, and problems.
 API Reference: Detailed information on all the functions, classes, and methods
exposed by an API, including parameters, return values, and usage examples.
 Release Notes: Information about changes, updates, bug fixes, and new features
introduced in each version.
1.2 Interpreting and evaluating documentation requirements
 Documentation requirements:
The specific criteria, standards, and guidelines for creating and maintaining documents in various
fields and industries.
Documentation should be clear, concise, and consistent. Ambiguities can lead to
misunderstandings and errors. Use standardized terminology and formats to enhance clarity.
 Common aspects:

Page 7 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Regulatory compliance, project documentation, quality management, software development,
product documentation, health and safety, and environmental management are some common
aspects that may have documentation requirements.
 Considerations:
Documentation requirements may vary depending on the context, industry, and regulatory
environment. They are important to ensure consistency, traceability, and compliance with
standards.
1.3 industry documentation standards
 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.

Documentation standards are guidelines, specifications, or best practices that provide a framework
for creating, formatting, and organizing various types of documents. These standards ensure

Page 8 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
consistency, clarity, and quality in documentation across industries and fields. Here is some
common documentation standards used in different domains:

 ISO (International Organization for Standardization):

 ISO 9001: Quality management system standards that include requirements for
documentation related to quality processes.
 ISO 27001: Information security management system standards with
documentation requirements for managing information security risks.
 ISO 14001: Environmental Management System (EMS)

The text describes the key steps to understand and assess the needs and standards for creating
effective documentation for different purposes and audiences. The text lists the following contents:

 Understand the purpose: Know the goal of the documentation.

 Identify the audience: Tailor the content to the target users.
 Review standards and regulations: Comply with industry or regulatory guidelines.
 Clarify content requirements: Determine what information to document.
 Consider format and structure: Follow a consistent and clear format.
 Verify version control and updates: Keep the documentation accurate and current.
 Evaluate accessibility requirements: Make the documentation accessible to all users.
 Feedback and iteration: Use feedback to improve the documentation over time
 How to investigate technical documentation standards: It gives some steps to research and
understand the standards for creating and maintaining technical documentation in different
industries or fields.
 Factors to consider: It mentions factors such as regulatory requirements, international
standards, industry-specific standards, government regulations, professional organizations,
and documentation examples from leaders in the field.

Page 9 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Why it matters: It implies that investigating technical documentation standards is important
for ensuring quality, compliance, and best practices in technical documentation

1.4 Defining and documenting 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.

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

Page 10 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Defining and documenting the scope of work is essential to ensure that the documentation project
meets its objectives, is well-structured, and aligns with the needs of the audience. Here's a step-
by-step guide specifically tailored for defining and documenting the scope of work in technical
documentation:

 Project Overview:
 Provide a concise overview of the technical documentation project. Include
information on the purpose of the documentation, target audience, and how it fits
into the larger context of the product or system.

 Documentation Objectives:
 Clearly articulate the objectives of the documentation. Define what the
documentation is expected to achieve, such as supporting end-users, aiding in
troubleshooting, or providing information for developers.
 Types of Documentation:
 Specify the types of documentation to be created. This could include user manuals,
API documentation, technical specifications, installation guides, and any other
relevant document types.
 Audience Analysis:
 Conduct an audience analysis to understand the knowledge level, roles, and
expectations of the target audience. Tailor the documentation to meet the needs of
different user groups.
 Content Inclusions and Exclusions:
 Clearly outline what content will be included in the documentation and what will
be excluded. This helps manage expectations and avoids unnecessary scope creep.
 Document Structure and Format:

Page 11 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Define the structure and format of the documentation. Specify how information will
be organized, the use of headings and subheadings, the inclusion of visuals, and
any style guide requirements.
 Collaboration and Review Process:
 Outline the process for collaboration among team members and subject matter
experts. Define how reviews will be conducted, including feedback collection and
revision processes.
 Tools and Technologies:
 Identify the tools and technologies that will be used for creating and managing
documentation. This could include documentation authoring tools, version control
systems, and collaboration platforms.
 Versioning and Updates:
 Establish a versioning system for the documentation. Define how updates,
revisions, and new releases will be managed to keep the documentation current
1.5 validation and confirmation of the scope of work
 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.

Here’s a list of possible elements you should consider adding to your scope statement:

 Business case and goals

Page 12 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
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.

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

Page 13 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
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.

 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

Page 14 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
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.

Consulting with the client to validate and confirm the scope of work for technical documentation
is a critical step to ensure alignment between your understanding and their expectations. Here's a
guide on how to effectively consult with the client for scope validation:

 Schedule a Kickoff Meeting:

 Initiate a kickoff meeting with key stakeholders, including representatives from the
client's side. This meeting provides an opportunity to introduce the documentation
team, clarify objectives, and discuss the scope.
 Review Initial Understanding:
 Present your initial understanding of the scope of work based on your research and
discussions. This serves as a starting point for discussion and ensures that both
parties are on the same page.
 Clarify Client Objectives:
 Allow the client to articulate their objectives and expectations for the technical
documentation. Encourage open communication to capture any additional
requirements or nuances that might not have been initially identified.
 Identify Key Stakeholders:
 Confirm and identify key stakeholders on the client's side who will be involved in
the review and approval process. Understand their roles and expectations regarding
the documentation.
 Discuss Audience and User Needs:

Page 15 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Review and discuss the identified audience for the documentation. Validate that the
client's expectations align with your understanding of the audience's needs and
knowledge levels.
 Present Document Types and Structure:
 Share your proposed types of documents and their structure. Discuss whether the
client has additional document types or specific structural preferences that need to
be considered.

Page 16 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Self-Check 1
Part I: True False Questions

1. Technical documentation is essential for users to effectively use products and technologies.
2. Effective technical documentation offers benefits such as increased customer retention,
increased sales, and saved time and effort.
3. Documentation process standards define the process that should be followed for document
production.
4. product technical documents and process technical documents are the two main types of
technical documentation

Part II. Choose the best answer.

1. Technical Documentation is information about

A. Application
B. Purpose
C. architecture of a product or service
D. All
2. Review the scope of work with all stakeholders to ensure that it accurately reflects
the project requirements.
A. Define quality standards
B. Identify risks
C. Define acceptance criteria
D. Review and finalize

Part III. Short Answer Questions

1. What is Technical Documentation?

2. What is mean by scope of the work?

Page 17 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Unit Two: Design documentation
This learning guide is developed to provide you the necessary information regarding the following
content coverage and topics:

 Identification of information requirements

 Creating document templates
 system functionality review
 information content meets requirements
 Validation of 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
 Create document templates
 Conduct the system review
 Extract content that meets information requirements
 Validate technical documentation structure

Page 18 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
2.1 Identification information requirements
 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).

Designing technical documentation involves careful planning and consideration of various

elements to ensure that the documentation effectively communicates complex technical
information to the intended audience. Here are key pieces of information required for designing
technical documentation:

Page 19 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Document Purpose and Objectives:
 Clearly state the purpose of the documentation. Is it for end-users, developers,
administrators, or a combination of audiences?
 Outline the specific objectives the documentation aims to achieve, such as providing
instructions, explaining concepts, or troubleshooting guidance.
 Audience Analysis:
 Understand the characteristics of the target audience, including their technical expertise,
roles, and knowledge level.
 Tailor the documentation to meet the needs and expectations of different user groups within
the audience.
 Document Scope:
 Define the scope of the documentation, specifying what topics will be covered and any
limitations or exclusions.
 Clearly communicate the boundaries of the documentation to manage user expectations.
 Document Structure:
 Establish a logical and user-friendly structure for the documentation.
 Define the hierarchy of sections, chapters, and subsections to facilitate easy navigation.
 Visual Design Elements:
 Determine the use of visual elements such as diagrams, charts, screenshots, and illustrations.
 Define a consistent style for visuals to enhance understanding and maintain a professional
appearance.
 Style Guide:
 Develop a style guide that outlines the preferred writing style, terminology, and formatting
conventions.
 Ensure consistency in language and presentation throughout the documentation.
 Document Format:
 Choose an appropriate document format, considering factors such as print vs. online, PDF vs.
HTML, or other formats based on user preferences.

Page 20 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Ensure that the format aligns with the distribution method and accessibility requirements.
 Interactive Elements:
 Identify opportunities for interactive elements, such as hyperlinks, cross-references, or
interactive tutorials.
 Enhance user engagement and facilitate easy navigation within the documentation.
 Version Control:
 Establish a version control system for the documentation to track changes and updates.
 Clearly indicate the document version and update history to keep users informed.
2.2 Creating document templates
 Style documents

Style can refer to the way a writer organizes 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).

Style also 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.

 Document templates: A practical way to create consistent, efficient, and standardized

documents for various purposes.

To create Document templates:

Page 21 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Identify the document type,
 outline key sections and components,
 define document structure,
 consider formatting and styles,
 create header and footer,
 insert placeholder text and images, include tables and graphs,
 Incorporate branding elements.
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 organization
 facilitating the handover of projects in the event of personnel or organizational 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.
 Streamline the document creation process, facilitate knowledge transfer, and maintain
visual coherence.

2.3 System functionality 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

Page 22 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
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, such as user guides

Page 23 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
 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.
 Building the better technical review

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

Information content meets requirements

Extracting content that meets information requirements involves identifying and retrieving specific
information from various sources.

 Information Extraction Process: The text describes a general process for extracting
information from various sources. It consists of the following steps:

 Define Requirements: Outline the specific information needed and the scope of
the topic.
 Identify Sources: Determine the potential sources of information, such as
databases, websites, or documents.
 Use Search Strategies: Use effective search methods to locate the required
information, such as keywords, Boolean operators, or filters.
 Evaluate Sources: Assess the credibility, reliability, and relevance of the sources,
considering the author, date, and context.
 Data Extraction Tools: Use tools or software that facilitate data extraction, such
as web scrapers, APIs, or data extraction software.

Page 24 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Read and Analyze: Read the sources thoroughly and extract relevant information,
paying attention to context, nuances, and biases. Analyze the data to ensure it meets
the requirements.

 Document Findings: Keep detailed notes of the extracted information,

documenting the source, key points, and contextual information.
 Organize Information: Organize the extracted information in a structured manner,
using categories, headings, or a system that aligns with the requirements.
 Verify Information: Cross-verify information from multiple sources to ensure
accuracy and consistency. Identify and resolve any discrepancies or conflicting
data.

2.5 Validation of technical documentation structure

Validating the structure of technical documentation is crucial to ensure clarity, completeness, and
effectiveness. Here are steps to validate the structure of technical documentation:
 Define Documentation Objectives:
 Clearly define the objectives of the technical documentation. Understand the purpose,
target audience, and expected outcomes.
 Check for Consistency:
 Ensure consistency in terminology, formatting, and style throughout the document.
Consistency enhances readability and understanding.
 Review Table of Contents:
 Check the table of contents to verify that it accurately reflects the document's structure.
Ensure all sections are appropriately listed and in the correct order.
 Evaluate Document Flow:
 Assess the logical flow of information. Ensure that topics are organized in a coherent
manner, and the document progresses logically from introduction to conclusion.

Page 25 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Examine Heading Hierarchy:
 Review the hierarchy of headings and subheadings. Ensure a clear and hierarchical
structure to guide readers through the document.
 Validate Section Introductions: Each section should have a clear introduction outlining
the purpose and content. Confirm that introductions provide context and set expectations.
 Verify Consistent Formatting:
 Ensure consistent formatting for headings, bullet points, numbered lists, fonts, and
other elements. Consistency contributes to a professional and polished appearance.
 Check for Redundancy:
 Eliminate redundant information. Each section should contribute to the overall
understanding without unnecessary repetition.
 Assess Visual Elements:
 Review the placement and relevance of visual elements such as images, diagrams,
charts, and tables. Visuals should enhance understanding and align with the adjacent
text.

Page 26 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Self-Check 2
Part I. True False Questions

1. Organizing your documentation is essential to make it coherent, logical, and comprehensive.

2. You need to organize your documentation according to the goals, tasks, and scenarios of your
audience
3. Formatting your documentation is important to make it easy to read, understand, and navigate.

Part II: Choose the best answer.

1. Before you start designing a document you must know about:

B. who will use the documents

C. what they will use the documents for, and how they will use the documents

D. what they are expected to do with the information in the document

2. Creating _____can help you maintain consistency in your technical documentation.

A. document templates
B. style guides
C. Format
D. A and B

3. The design of technical documents includes deliberate choice of:

A. Genre

B. Function

C. Structure

D. All

Page 27 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Part III: Answer the following questions briefly.

1. What is Group of Data Elements

2. What is mean by documentation Review
3. By what way you can Share the developed documentation

Page 28 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Unit Three: Develop documentation
This learning guide is developed to provide you the necessary information regarding the following
content coverage and topics:
 Writing technical documentation
 Translating technical terminology
 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
 Apply content format and style

Page 29 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
3.1 Writing technical documentation

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

Page 30 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  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.

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.

Writing technical documentation is a critical skill for effectively communicating complex

information to various audiences. Here's a guide on how to write technical documentation:

 Understand Your Audience:

Page 31 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Identify your target audience, whether they are end-users, developers, system
administrators, or a combination. Tailor your language, tone, and level of detail to meet
their needs.
 Define the Purpose:
 Clearly define the purpose of your documentation. Is it instructional, reference
material, troubleshooting guide, or a combination? Understanding the purpose helps
shape the content and structure.
 Organize Information Logically:
 Structure your documentation in a logical and hierarchical manner. Use headings,
subheadings, and bullet points to break down information into manageable sections.
 Start with an Introduction:
 Begin with an introduction that outlines the scope, objectives, and intended audience.
Provide a brief overview of what the documentation covers.
 Use Clear and Concise Language:
 Use plain and straightforward language. Avoid jargon and unnecessary technical terms,
or explain them when they are essential. Strive for clarity and simplicity.
 Provide Context:
 Place technical information in context. Help readers understand the significance of the
information and how it fits into the broader context of a system or process.
 Include Visuals:
 Use visuals such as diagrams, flowcharts, screenshots, and tables to illustrate concepts.
Visuals enhance understanding and make the documentation more engaging.
 Write Step-by-Step Instructions:
 If your documentation includes procedures or instructions, present them in a step-by-
step format. Clearly outline each step and use action verbs.

Page 32 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Include Examples and Use Cases: Provide real-world examples and use cases to
demonstrate how the information is applied. This helps users relate the theoretical
knowledge to practical scenarios.

Fig. 3.1. Image that shows creating technical documentation

3.2 Translating technical terminology

Translating technical terminology requires a thoughtful and accurate approach to ensure that the
meaning of specialized terms is preserved in the target language. Here are some guidelines for
translating technical terminology

Page 33 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Translating technical terms: A guide for translating specialized terms in a technical
context.
 Context: Understand the subject matter, industry, and field of technology.
 Glossary: Create and use a glossary of terms in both languages.
 Industry standards: Follow established terminology in the technical field.
 Research: Read technical publications in the target language.
 Audience: Adjust the translation to suit different levels of expertise.
 Consistency: Use the same translation for the same term throughout the document.
 Transliteration: Use similar sounds in the target language for terms with no equivalent.
 Culture: Consider cultural connotations of terms and avoid inappropriate translations.
 Experts: Consult with technical professionals who are fluent in both languages.

3.3 Applying content format and style

Applying a consistent format and style to technical documentation is essential for clarity,
readability, and overall effectiveness. Here are guidelines to help you apply a cohesive format and
style to your technical documentation:

 Use a Clear Document Structure:

 Organize your documentation with a logical and hierarchical structure. Use
headings, subheadings, and a table of contents to guide readers through the content.
 Consistent Formatting:
 Maintain consistent formatting throughout the document. Ensure uniformity in font
styles, sizes, and colors. Consistency enhances professionalism and readability.
 Headings and Subheadings:
 Structure your document with clear and descriptive headings. Use a hierarchy to
distinguish main sections from subsections. This aids navigation and
comprehension.

Page 34 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Bullet Points and Numbered Lists:
 Use bullet points or numbered lists to break down complex information into
digestible points. Lists improve readability and make information more scannable.
 Visual Elements:
 Incorporate visuals such as diagrams, charts, screenshots, and illustrations to
complement text. Ensure that visuals are relevant, labeled, and have clear captions.
 Consistent Terminology:
 Establish and adhere to a consistent set of technical terms. Create a glossary to
ensure uniformity in terminology usage throughout the documentation.
 Emphasize Key Points:
 Use formatting elements like bold, italics, or underline to emphasize key points,
important terms, or warnings. Be consistent in how you apply these formatting
elements.
 Page Layout:
 Design a clean and professional page layout. Pay attention to margins, spacing, and
overall aesthetics. A well-organized layout contributes to a positive user
experience.
 Document Length:
 Consider the optimal length for your document. Long documents should be well-
structured with clear breaks, and shorter documents should still cover essential
information.

Page 35 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Self-Check 3
Part I: True or False Questions

1. An editorial calendar can help you stay organized and ensure your content gets published on
time.
2. Visuals are essential to any content style guide.
3. The final step in creating your own content style guide is to create a template.

Part II: Choose the best answer

4. Among the following one is important to write effective technical documentation.

A. Identify your audience and goals.
B. Create a plan and outline.
C. Build technical documentation templates
D. All
5. every standard technical documentation template includes the following:
A. A table of contents (insert jump-links when applicable) to help readers ascertain the
areas they need help with.
B. A clear title with keywords.
C. A subheading or intro paragraph that highlights the documentation's purpose.
D. D. All
6. All technical documentation should have
A. Goals: What’s your reader’s aim
B. Learning objectives
C. An outline
D. All

Page 36 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Part III: Answer the following questions briefly

1. Write the best practices for managing terminology

2. How to use terminology and glossaries
3. Write steps used to create Content Style Guide

Page 37 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Unit Four: Evaluating and edit documentation
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

Page 38 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
4.1 Submitting technical documentation
Submitting technical documentation for review is a crucial step to ensure accuracy, clarity, and
effectiveness. Here's a guide on how to prepare and submit technical documentation for review
Organizations can do document reviews informally or as part of a formal process.

 How to prepare and submit technical documentation for review:

It provides a step-by-step guide on how to finalize, format, and submit technical documentation
for review by reviewers.

 The importance of review: It emphasizes that review is a crucial step to ensure accuracy,
clarity, and effectiveness of technical documentation.
 The components of submission: It lists the components of a submission, such as the
document version, supporting materials, cover letter, and review goals.
 The tools for review: It suggests using a collaborative document review tool that allows
reviewers to add comments directly to the document, such as Google Docs or Microsoft
Word’s Track Changes.

4.2 Gathering and analyzing feedback

Gathering and analyzing feedback on technical documentation is a crucial step in improving the
quality, clarity, and effectiveness of the documentation. Here's a guide on how to gather and
analyze feedback effectively:

 Gathering Feedback: How to identify reviewers, select review tools, provide clear
instructions, encourage specific comments, establish a deadline, consider a review meeting,
and include a feedback form for technical documentation.

Page 39 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Analyzing Feedback: How to compile, prioritize, identify trends and patterns, and resolve
conflicting feedback for technical documentation.
 Feedback Channels: How to offer multiple channels for feedback, such as email,
Comments or feedback forms.

4.3 Incorporating alternatives to the technical documentation

Incorporating alternatives to technical documentation involves providing additional formats,
resources, or methods to enhance accessibility and understanding for a diverse audience. Here are
some strategies for incorporating alternatives into technical documentation:

 Multimodal Documentation: Offer documentation in multiple formats, such as text,

audio, and video. This accommodates users with different learning preferences and
accessibility needs.
 Interactive Guides: Create interactive guides or tutorials that allow users to actively
engage with the content. This can include clickable elements, simulations, or step-by-step
interactive experiences.
 Visual Aids and Diagrams: Enhance textual information with visual aids, diagrams,
charts, and info graphics. Visual elements can improve comprehension, especially for
complex technical concepts.
 Video Walkthroughs: Provide video walkthroughs or demonstrations alongside written
documentation. Visual demonstrations can be particularly helpful for users who prefer a
more hands-on learning approach.
 FAQs and Troubleshooting Guides: Include Frequently Asked Questions (FAQs) and
troubleshooting guides to address common user queries. This helps users quickly find
solutions to issues they may encounter.

Page 40 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
  Use Case Examples: Incorporate real-world use case examples to illustrate how technical
features or processes can be applied in practical scenarios. Examples make abstract
concepts more tangible.
 Visual Mapping: Use mind maps or visual mapping tools to represent relationships and
connections between different components. Visual representations can aid in
understanding complex systems.
 Accessible Text Formats: Ensure that text-based documentation is accessible. Use clear
headings, bullet points, and concise language. Provide alternative text for images to
accommodate users with visual impairments.
 Translations: Offer documentation in multiple languages to cater to a global audience.
Ensure that translations

4.4 Editing technical documentation

Editing documentation based on feedback is important for continuous improvement. The following
possessions are:

 Review feedback: Read all feedback and note common themes and suggestions.
 Categorize feedback: Organize feedback into content, clarity, formatting, accuracy, etc.
 Prioritize changes: Address critical issues first, then minor improvements.
 Address accuracy: Verify information with experts or sources and correct errors.
 Clarify ambiguity: Rephrase unclear sections and add examples or explanations.
 Check consistency: Ensure consistent terminology, formatting, and style throughout the
document.
 Update visuals: Improve visuals and diagrams to align with text and convey information.
 Incorporate examples: Add relevant examples or use cases to make content more practical.
 Verify references: Check and update cross-references or hyperlinks for easy navigation

Page 41 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Self-Check 4
Part I: True or False Questions

1. The primary focus of technical document editing is to ensure the accuracy and clarity of the
information presented in the text.
2. Technical editors work with writers to help them produce clear, accurate content.
3. It’s great that you’re gathering feedback on your technical document.

Part II: Choose the best answer

1. Technical document editing is a process of reviewing technical documents, including:
a. user manuals
b. Reports
c. Instructions and briefs.
d. All
2. _________is an essential part of the engineering process and can help you improve the
quality of your work.
a. Documentation
b. Feedback
c. Template
d. All

3. If document is inaccurate, and not be used.

A. The document is approved
B. The documents need changes
C. The document is voided/rejected

Page 42 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
References
Books

1. “Technical Writing Process: The simple, five-step guide that anyone can use to create
technical documents such as user guides, manuals, and procedures" by Kieran Morgan
2. "Read Me First! A Style Guide for the Computer Industry" by Sun Technical Publications
3. "The Elements of Technical Writing" by Gary Blake and Robert W. Bly
4. "Microsoft Manual of Style for Technical Publications" by Microsoft Corporation
5. "Every Page Is Page One: Topic-Based Writing for Technical Communication and the
Web" by Mark Baker

URL:

https://techwhirl.com/

https://document360.com/blog/technical-documentation/

https://technicalwriterhq.com/documentation/technical-documentation/

https://alg.manifoldapp.org/read/open-technical-communication/section/19abea6b-932a-
4efd-a70d-9f1123dd4b08

Page 43 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023
Developer’s Profile

Mobile
N Qualific Field of Organization/
Name numbe E-mail
o ation Study Institution
r
1 Frew M-Tech Network & Bishoftu 091178 [email protected]
Atkilt Information Polytechnic 7374 m
Security College

2 Gari MSc ICT Gimbi Polytechnic 091781 Garilencha12@gmail.

Lencha Managment 9599 com

3 Kalkidan BSc Computer Entoto Polytechnic 097833 kalkidaniel08@gmail.

Daniel Science 6988 com

4 Solomon M-Tech Computer M/G /M 091857 solomonmelese6@gm

Melese Engineering /Polytechnic 8631 ail.com
College

5 Tewodros MSc Information Sheno Polytechnic 091206 girmatewodiros

Girma system College 8479 @gmail.com

6 Yohannes BSc Computer Entoto Polytechnic 092322 yohannesgebeyehu73

Gebeyehu Science College 1273 @gmail.com

Page 44 of 47 Ministry of Labor and Create Technical Version-I

Skills Documentation
Author/Copyright November, 2023