Web Development and Database Administration

Level IV.
Competency : Creating Technical Documentation
Module code: EIS WDDBA4 M091123
Nominal duration: 30 Hour

1
Creating Technical Documentation has Four units
Unit One: Documentation needs identification
Unit Two: Design documentation
Unit Three: Develop documentation
Unit Four: Evaluating and edit documentation

2
Unit Three: Develop documentation
Presenter: Asnake Bogale
June. 2024

3
Objectives of Develop documentation
upon completion of this learning guide, you will be able to:

Write technical documentation

Translate technical terminology
Apply content format and style

4
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. 5
Cont …
Technical writing is necessary for almost anyone who works in
IT, communications or systems.
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.
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.
6
Cont…
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

7
Cont…
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.

8
Cont…
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:
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 the9
Cont …
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.

10
Cont ….
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.
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. 11
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
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.

12
 Cont…
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.
13
 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.
14
Cont…

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

15
Cont…
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.
16