diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index be7bc6d6ad..7aef20076c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -97,6 +97,9 @@ subdirectory. While it is possible to use HTML in Markdown documents for tables and images, it is preferred to use the Markdown style as it's much easier to read. +See a detailed guide on documentation contributions +[here](https://docs.hotosm.org/techdoc). + ### Coding Style Python enforces a certain amount of style due to indent levels. Unlike diff --git a/docs/Guide-On-Improving-Documentation.md b/docs/Guide-On-Improving-Documentation.md deleted file mode 100644 index bde1ed7eb4..0000000000 --- a/docs/Guide-On-Improving-Documentation.md +++ /dev/null @@ -1,155 +0,0 @@ -# Structures To Improve GitHub Documentation - -## Overview - -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. diff --git a/mkdocs.yml b/mkdocs.yml index a87b000f17..75c163d07c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,7 +69,6 @@ nav: - About: About.md - Installation: INSTALL.md - Contribution Guidelines: CONTRIBUTING.md - - Documentation Contribution: Guide-On-Improving-Documentation.md - Code of Conduct: https://docs.hotosm.org/code-of-conduct - FAQ: FAQ.md - User Manuals: