Basics of Creating Good Documentation

Introduction

Documentation is an integral part of all the business domains. Documentation plays a pivotal role in bridging the communication gap between man and machine! Neat and well-organized documentation not only communicates the information in effective manner but also reflects the quality of work.

In a typical SDLC (Software Development Life Cycle), documentation is also known as Technical Communication.

Technical Communication is the process of conveying usable information about a specific domain to an intended audience in a clear and concise manner.

If we can change Toni Morrison's quote little bit, then we can say,

If there's a document you really want to read, but it hasn't been written yet, then you must write it. 

In this article we will cover the following key areas:

• Improvement Areas
• General Tips
• Documentation Standards
• Layout Design
• Look and Feel
• Language Expertise
• Document Formatting
• Microsoft Word

Improvement Areas

In general, the following areas need to be strengthened:

• Document intent needs to come out far more clearly
1. In order to achieve this, Purpose section of the document should be written in such a manner that the user should understand what s/he should expect from the document.
• Content Layout - plan the overall layout, define your objective
• Improve Language- sentence structure, organization of thoughts, choice of words
1. Language is one of the most important aspects of quality documentation.
2. Precise and grammatically correct language should be used while writing technical documents.
3. Sentences should be short and crisp.
• Information Flow - hierarchy of content
1. Lucid information flow should be attained throughout the document.
• Use of images - Capturing, labeling, zooming a screen, screen clarity
1. If you have to use any images / screenshots, then sophisticated screen capture tools should be used to ensure maximum screen clarity.
2. Each image should be numbered and titled.
• Improve look and feel
• Know your audience and their requirements
1. Audience’s requirements and knowledge level should be kept in mind while creating the documentation.
2. Using unnecessary jargon or verbose writing should be avoided.
• Guidelines for printed documentation are different

General Tips

1. Clear title should be given to the document.
2. Document Revision History needs to come in the beginning of the doc.
3. Use Arial / Verdana font as against Times New Roman.
4. Define Notational Conventions used in a document.
5. Always have proper indentation defined for the Headings and the Body Text. Use a hierarchical structure for the Headings, such as, for Heading 1 (Arial, 16pt, Bold) then for Heading 2 (Arial, 14pt, Bold).
6. Use proper Header and Footer for each individual page. For separate sections use a Section Break to have different Headers and Footers.
7. Use Border and Shading to draw lines in Header and Footer. This helps to demarcate the header from the content.
8. Use a distinct style for table headers and description.
9. Add colors to the shade the table.
10. Text within a table should be left aligned or center aligned. The alignment selected needs to be consistent throughout the document.
11. All headings must be followed by text. Never place one heading directly after another without intervening text. Such headings are called widowed headings.
12. An abbreviation needs to be expanded the first time it is used in a document.
13. Screen shots need to be referenced and not copy pasted into a doc.
14. Images should be saved as jpeg but never a bmp. This increases the file size.
15. Always take a complete screenshot and then resize. Use Table properties to format the table.
16. Include a TOC for images as well as tables used in the document.
17. Label all the tables and images.
18. Refrain from using double inverted commas for screen titles, labels and button names. Instead use distinct styles and refer to them in the notational conventions section.
19. Incomplete bullet sentences need not be followed by a period.

Documentation Standards

Documentation standards comprise a set of defined attributes to be used across the document to ensure consistency, better readability and understandability.

These standards are meant for those who create, review, inspect and approve documentation.

Why do we need standards?

1. Saves time and effort while navigating through documents
2. Removes the confusion regarding distinct styles in different documents
3. Offers uniform look to the document that enhances its usability

Documentation standards are as important as the uniforms are in military. Documentation standards offer a distinctive look to the documents which if followed scrupulously, form the brand image of the organization.

For example:

1. Click the drop down arrow. The dropdown displays various options.

2. Select appropriate option from the drop-down

3). Click Ok.

In the above example, dropdown has been written using three different styles. Also, numbering is inconsistent. This hampers consistency and creates confusion.

• Define documentation standards before creating documentation.
• Get these standards reviewed and approved by the concerned authority.
• Explain the defined standards in the beginning of the document.
• Stick to them while you create the document.

Layout Design

Setup a page layout before you start documentation work.

Any document prepared for the customer should preferably include the following information presented in the sequence given below.

1. Cover pages (such as, title page, copyright page)
2. Contents
3. Table of Figures and Tables
4. Introduction to the document
5. Chapters
6. Glossary
7. Index

Look and Feel

Look and feel of the document connote the following:

1. Information architecture – should be designed adeptly
2. Defined document structure – should enhance readability
3. Color combinations – should gel well with the tone of the document
4. Placement of diagrams / images (if any) – should be appropriate
5. Usability – required info should be easily locatable

Look and feel serves two general purposes:

1. It provides branding, reflecting an organization’s image.
2. It increases ease of use since users can translate their experiences to other documents as well.

Consistent and good look and feel enhances the documentation and results in greater usability.

It is a natural feeling of the human beings to look at beautiful things. A thing of beauty is a joy forever. So try to enhance the look and feel of the document. This doesn’t mean you should add unnecessary colors, images or geometrical figures to the document.

Document should look clean, neat and legible. Your document should be usable. Usability engineering is an extremely important aspect of all the industry domains.

A simple pamphlet that the guy standing outside our main gate hands to you can be analyzed for its usability.

They give contact details at a place where a human eye can easily see them. Features/advantages are listed out in a bulleted list.

Author: Oxygen

Other articles by this author

• Python Refresher - Numbers (1 minute) Monday, 01 May 2023
• Know the Differences Between Co-op and Internship Wednesday, 22 February 2023
• Can't afford Management courses? DIY learning options. Wednesday, 04 January 2023
• How to fake yourself to success? Thursday, 12 August 2021
• Social Media – Should you POST it?! Monday, 02 August 2021