-
Notifications
You must be signed in to change notification settings - Fork 51
Style Guide
Our mapping guides used internally by the @mapbox/team-data is a great resource for getting started with editing OpenStreetMap (OSM). Since it went public, it became a great resource for the larger OpenStreetMap community especially during the HOT Activations in Mexico and Afghanistan. This guide attempts to document the basic guidelines in maintaining and updating our mapping guides.
Sections should be concise and not 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.
If the point of the document is to showcase a new feature, then it does not belong in the guide. Write an article or a blog post about it. If it is necessary to point out a technical advantage of a feature, then do so from a technical standpoint.
Bad
MBtiles are a great way to publish super cool datasets!
Good
MBtiles allow you to efficiently publish data.
Avoid using 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 ...
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
When providing step-by-step instructions, use direct commands or requests. Avoid using “we” and “let’s”.
Bad
Now let’s add a shapefile by ...
Good
Add a shapefile by ...
I like to introduce jargon or acronyms like I would introduce two people. Start with full names and explain what they do. Then after that they'll start using first names, have inside jokes, and start hanging out without you on Instagram.
Avoid the words: just, easy or simple, of course.
Use sentence case. Do not capitalize second and later 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 Layer
Good
Creating a new layer
It is recommended that the gerund (the -ing form in English) be used unless a more common noun form is available. For example, an article on swimming is better than one on swim.
Bad
Create a new layer
Good
Creating a new layer
Create page titles that are in the singular form. 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
The GUI convention styles are intended to mimic the appearance of the GUI. In general, the goal 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 guide.
-
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 theCtrlkey and then press theBkey. -
Code or variables are indicated by a fixed-width font, for example:
some commands or variables here -
State in the instructions if the GUI is platform specific (Windows, Linux or Mac).
- Images should be no more than
800x600 px. If larger than that, the icons appear too small. - Use animated GIFs to show a series of steps.
- The focus of the action should be clear and should not have distracting elements.
- Animations should be limited to under 5 seconds.
- Use animated GIFs sparingly.
- Search for prior art (i.e. learnosm.org, wiki.openstreetmap.org). Can you improve the existing document?
- Post a ticket at /mapping/issues. Label as
mapping-guide. - Create content with a secret gist.
- Test if it works on all platforms.
- Ask your buddy to review.
- Re-write.