
Documentation Style Guide Paste of data from hackpad mentioned in https://github.com/hotosm/learnosm/issues/82 Style Guidelines This document provides a set of general guidelines for developing and editing new sections. The goal is to ensure sections are clear, consistent, and easy to read. Note: This guide is for the EN version and is not necessarily applicable to other languages. Initial guidelines were based on Geoserver’s Style Guide. Content conventions Be concise Sections should be concise and not just a brain dump. Reference material should contain short pages and be easy to refer to without having to scroll through a large volume of text. Avoid marketing If the point of the document is to showcase a new feature it does not belong in the documentation. Write an article or a blog post about it. If it is necessary to point out a technical benefit of a feature then do so from a technical standpoint. Bad Super-overlays are a great way to publish super cool datasets awesomely in Google Earth! Good Super-overlays allow you to efficiently publish data via Google Earth. Be professional Avoid the use of slang or other “colorful” language. The aim is to be informative, not to keep the reader amused. Avoiding slang helps keep the document accessible to as large an audience as possible. Bad Next, fire up whatever tool you use to browse the web and point it in the direction of … Good Next, start your web browser and navigate to … Avoid contractions We can never be sure the level of comfort with a language a reader has, contractions increase the difficulty for non native speakers or readers of a language Bad `We've, you're, don't` Good `We have, you are, do not` Use direct commands When providing step-by-step instructions, use direct commands or requests. Avoid the use of “we” and “let’s”. Bad Now let’s add a shapefile by … Good Add a shapefile by … `received as feedback: do not use "In this chapter we will"` Naming conventions Capitalization of page names Each word in the page name should be capitalized except for articles (such as “the”, “a”, “an”) and conjunctions (such as “and”, “but”, “or”). A page name should never start with an article. Bad Adding a shapefile or postgis table Good Adding a Shapefile or PostGIS Table Bad The Shapefile Tutorial Good Shapefile Tutorial Capitalization of section names Do not capitalize second and subsequent words unless the title is almost always capitalized in English (like proper names). Thus, capitalize John Wayne and Art Nouveau, but not Video Games. Bad Creating a New Datastore Good Creating a new datastore Verb usage It is recommended that the gerund (the -ing form in English) be used unless there is a more common noun form. For example, an article on swimming is better than one on swim. Bad Create a new datastore Good Creating a new datastore Avoid plurals Create page titles that are in the singular. Exceptions to this are nouns that are always plural (scissors, trousers), a small class that requires a plural (polar coordinates, Bantu languages, The Beatles). Bad Templates tutorial Good Template tutorial GUI convention The GUI convention styles are intended to mimic the appearance of the GUI. In general, the objective is to use the non-hover appearance, so a user can visually scan the GUI to find something that looks like the instruction in the manual. Menu and toolbar commands are shown as bold letters and (if available) preceded by an icon image, for example, File `image`. A series of commands are written with `>`. For example: File > New Project. Keystroke combinations are shown as `Ctrl+B`, which means press and hold the `Ctrl` key and then press the `B` key. Code or variables are indicated by a fixed-width font, for example: `some commands or variables here` Note, Text within this box indicates a tip, suggestion, warning or caution. Indicate in the instructions if the GUI is platform specific (Windows, Linux or Mac). Formatting Refer to Markdown post guidelines. `https://github.com/hotosm/learnosm/wiki/Markdown-post-guidelines http://daringfireball.net/projects/markdown/syntax` Attribution of images and screen-shots Not sure how: hotosm/learnosm#198 Outline of module/topic sections `Overview - discuss what briefly what this section is about and the expected outcome Detailed steps Summary` Illustrations and Images Labeling images Images should be labeled with numbers and arrows pointing to the specific parts of the image the number references. Below the image the numbers should be repeated with the textual description of what the arrow is pointing to in the image. Text labels or descriptions should never be part of the image itself. This is done so image label translations are easier and it is less likely a new image will have to be generated for every language, although that might still be required if the interface in the image needs to be in the local language. References GNOME Style Guide - https://developer.gnome.org/gdp-style-guide/stable/ Geoserver Style Guide - http://docs.geoserver.org/latest/en/docguide/style.html Documenting Python - http://docs.python.org/devguide/documenting.html GH Issue on the topic - hotosm/learnosm#82 Return to top of page Was this chapter helpful? Let us know and help us improve the guides!

Documentation Style Guide

Paste of data from hackpad mentioned in https://github.com/hotosm/learnosm/issues/82

Style Guidelines

This document provides a set of general guidelines for developing and editing new sections. The goal is to ensure sections are clear, consistent, and easy to read.

Note: This guide is for the EN version and is not necessarily applicable to other languages. Initial guidelines were based on Geoserver’s Style Guide.

Content conventions

Be concise

Sections should be concise and not just a brain dump. Reference material should contain short pages and be easy to refer to without having to scroll through a large volume of text.

Avoid marketing

If the point of the document is to showcase a new feature it does not belong in the documentation. Write an article or a blog post about it. If it is necessary to point out a technical benefit of a feature then do so from a technical standpoint.

Bad Super-overlays are a great way to publish super cool datasets awesomely in Google Earth! Good Super-overlays allow you to efficiently publish data via Google Earth.

Be professional

Avoid the use of slang or other “colorful” language. The aim is to be informative, not to keep the reader amused. Avoiding slang helps keep the document accessible to as large an audience as possible.

Bad Next, fire up whatever tool you use to browse the web and point it in the direction of …

Good Next, start your web browser and navigate to …

Avoid contractions

We can never be sure the level of comfort with a language a reader has, contractions increase the difficulty for non native speakers or readers of a language

Bad

We've, you're, don't

Good

We have, you are, do not

Use direct commands

When providing step-by-step instructions, use direct commands or requests. Avoid the use of “we” and “let’s”.

Bad Now let’s add a shapefile by …

Good Add a shapefile by …

 received as feedback:

do not use "In this chapter we will"

Naming conventions

Capitalization of page names

Each word in the page name should be capitalized except for articles (such as “the”, “a”, “an”) and conjunctions (such as “and”, “but”, “or”). A page name should never start with an article.

Bad Adding a shapefile or postgis table Good Adding a Shapefile or PostGIS Table Bad The Shapefile Tutorial Good Shapefile Tutorial

Capitalization of section names

Do not capitalize second and subsequent words unless the title is almost always capitalized in English (like proper names). Thus, capitalize John Wayne and Art Nouveau, but not Video Games.

Bad Creating a New Datastore Good Creating a new datastore

Verb usage

It is recommended that the gerund (the -ing form in English) be used unless there is a more common noun form. For example, an article on swimming is better than one on swim.

Bad Create a new datastore Good Creating a new datastore

Avoid plurals

Create page titles that are in the singular. Exceptions to this are nouns that are always plural (scissors, trousers), a small class that requires a plural (polar coordinates, Bantu languages, The Beatles).

Bad Templates tutorial Good Template tutorial

GUI convention

The GUI convention styles are intended to mimic the appearance of the GUI. In general, the objective is to use the non-hover appearance, so a user can visually scan the GUI to find something that looks like the instruction in the manual.

Menu and toolbar commands are shown as bold letters and (if available) preceded by an icon image, for example, File image.
A series of commands are written with >. For example: File > New Project.
Keystroke combinations are shown as Ctrl+B, which means press and hold the Ctrl key and then press the B key.
Code or variables are indicated by a fixed-width font, for example:
```
    some commands or variables here
```
Note, Text within this box indicates a tip, suggestion, warning or caution.
Indicate in the instructions if the GUI is platform specific (Windows, Linux or Mac).

Formatting

Refer to Markdown post guidelines.

https://github.com/hotosm/learnosm/wiki/Markdown-post-guidelines

http://daringfireball.net/projects/markdown/syntax

Attribution of images and screen-shots

Not sure how: hotosm/learnosm#198

Outline of module/topic sections

Overview - discuss what briefly what this section is about and the expected outcome

Detailed steps

Summary

Illustrations and Images

Labeling images

Images should be labeled with numbers and arrows pointing to the specific parts of the image the number references. Below the image the numbers should be repeated with the textual description of what the arrow is pointing to in the image. Text labels or descriptions should never be part of the image itself. This is done so image label translations are easier and it is less likely a new image will have to be generated for every language, although that might still be required if the interface in the image needs to be in the local language.

References

GNOME Style Guide - https://developer.gnome.org/gdp-style-guide/stable/
Geoserver Style Guide - http://docs.geoserver.org/latest/en/docguide/style.html
Documenting Python - http://docs.python.org/devguide/documenting.html
GH Issue on the topic - hotosm/learnosm#82

Return to top of page

Was this chapter helpful? Let us know and help us improve the guides!