From 450fae63e9315672242335833a6918677ce75b78 Mon Sep 17 00:00:00 2001 From: spwoodcock Date: Thu, 20 Jun 2024 17:54:06 +0100 Subject: [PATCH] docs: move fmtm section on writing tech docs here --- docs/techdoc/README.md | 154 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) diff --git a/docs/techdoc/README.md b/docs/techdoc/README.md index 6daff7e..82c4d72 100644 --- a/docs/techdoc/README.md +++ b/docs/techdoc/README.md @@ -32,3 +32,157 @@ You can visit the Humanitarian OpenStreetMap Team at and check out our pinned projects or browse through the full family of [HOTSM projects](https://github.com/orgs/hotosm/repositories). + +## Structures To Improve GitHub 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. + +### Goals + +1. Highlight the definitions of each type of documentation that are + commonly used on Github. +2. Provide a foundation to lay information on top of, in order to + produce efficient documentation about any product or project in the + future. +3. List key parts of each documentation type that aid the flow and + experience of the reader. +4. Outline general tips to improve already existing documentation. + +### Common Documentation Types On Github + +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** + +#### 1. Structure for Product 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. + +#### 2. Structure for Project Documentation + +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 + +#### 3. Structure for System Documentation + +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**. + +#### 4. Structure for Process Documentation + +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. + +### Improving Existing Documentation + +1. **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. + +2. **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. + +3. **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.” + +4. **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. + +5. **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. + +6. **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. + +7. **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.