-
-
Notifications
You must be signed in to change notification settings - Fork 43
Guide On Improving Documentation
An overall documentation structure outline, that cuts across; Project, Product, System and Process documentation. These structures can be replicated for all forms of documentation needed by HOTOSM. It also includes specific tips for improving already existing documentation.
- Highlight the definitions of each type of documentation that are commonly used on Github.
- Provide a foundation to lay information on top of, in order to produce efficient documentation about any product or project in the future.
- List key parts of each documentation type that aid the flow and experience of the reader.
- Outline general tips to improve already existing documentation.
I have found 4 main documentation types through my own personal research. They can all be written individually but often coincide to complement specific parts of each other. For example, Product documentation may include some Process documentation under the Usage section, demonstrating how to use that product. These 4 types in full, are as follows:
- Product Documentation
- Project Documentation
- System Documentation
- Process Documentation
Product documentation is the process of recording key information (almost everything you need to know) about a product, including how to use it. Product documentation may have form of Process documentation within it (this will be further explained later on). A flexible and reusable structure of essential components of product documentation is as follows:
- Overview
- Introduction: What the product is, what it does, the target audience, etc.
- Features: A breakdown of each integral part of the product, their functionality and purpose
- Benefits: How the features give users an edge over other similar products. In other words, what’s in it for the user.
- Usage: A step by step process of how to use the product
- Support / Frequently Asked Questions (about the product)
- License
The points stated above can be used in that order and can also be switched around based on convenience and the type of product. Additionally, other points can be added if necessary, but these are what I believe to be some of the most important.
Project documentation is the process of recording the key project details that are needed to implement a project. It’s like a roadmap of what the project is and all necessary information about what it entails. Main structural components are in the following order:
- Overview
- Vision
- Aim / Mission
- Introduction
- Project plan
- Project schedule
- Tools and Features
- Access
- Resources
- Support / Guidelines
System documentation is an all-encompassing record of details of a full working system. It is very similar to the structure of product documentation but it’s usually on a wider scale. It may even include some forms of product and process documentation within it. In addition to the structure of product documentation above, other key components it might include are: architecture design, program source code and maintenance / help guide.
Process documentation is capturing and listing all steps involved in doing a task. It is the full explanation of a process, step by step. Process documentation is very useful in other documentation forms. As mentioned earlier, it can be used within System, Product or Project documentation, to explain a process. The format is usually:
- Overview
- Introduction
- Explanation steps (breakdown of the task)
- Help (if any problems occur while acting on the steps)
The structures I have suggested above are similar, consistent and can be easily replicated for various projects, systems and products. They work well when integrated together, balancing out issues where necessary. Each structure also serves as a foundation that can be added to and built upon.
-
Acronyms should be stated in full before repetitive use. Acronyms like ODK, OSM, etc, should be stated in full before use or after each use within brackets e.g ODK (ODK). This negates confusion for readers / users and just simplifies things.
-
Important features should be put in bold. For example “select from map” and ‘’ODK Collect” can be easily overlooked by readers if they aren't highlighted, even though they are important features.
-
Generally simplifying words and phrases. This makes documentation more user friendly and much easier to understand, since users come from all different backgrounds. For example:
“ODK incorporates a new functionality” can become “ODK has brought in a new feature”.
“Field Mappers select (or are allocated) individual tasks within a project’s AOI” could be changed to “Field Mappers choose or are given tasks that are part of a project’s Areas Of Interest.”
-
Avoid long paragraphs. Short paragraphs that pass a clear message are less clumsy and flustering for readers. Breaking down topics into little, easy to understand chunks, is more user friendly.
-
Maintain a positive tone in the writing.. Keep the text positive and informative. Avoid words like ‘obviously’ and ‘basically’, that may be interpreted as demeaning or condescending. Do not expect readers to have a certain amount of knowledge on specific aspects, break down everything that needs to be broken down.
-
Constantly update your documentation. Projects, products and systems are always evolving. Thus, it is necessary to keep documentation up to date with any new changes.
-
Consistency in the documentation format. Maintaining consistency is a key aspect of creating clear and effective documentation.This consistency includes but is not limited to elements like numbering, font styles, heading sizes, and spacing.
Using the same font for all headings and subheadings can help readers quickly identify important sections of the document. Similarly, using consistent spacing between paragraphs and sections can make the document more visually appealing and easier to follow. This helps to create a documentation that is clear, effective, and easy to use.