docs: move fmtm section on writing tech docs here

docs/techdoc/README.md

@@ -32,3 +32,157 @@ You can visit the Humanitarian OpenStreetMap Team at
 <https://github.com/hotosm> 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.