Documentation Style Guide
Style guide for GeoServer documentation.
This page is a set of documentation guidelines for those contributing to GeoServer documentation.
Avoid too much information
Documentation should be concise and not just a brain dump. If the point of the document is to share your thoughts and insights, it belongs in a blog post. There are cases where a document should be verbose, such as the history of the project for instance, but these cases are the exception. For the most part keep it clear, concise, and to the point.
No marketing
Avoid marketing babble. If the point of the document is to showcase a new feature it does not belong in the user or developers guide. 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.
Super overlays are a great and wiz-bang way to publish big datasets in Google Earth.
Super overlays allow you to publish data in Google Earth in a way that prevents overloading Google Earth with too much data.
No slang
Do not use slang or other "colorful" language. The point of a technical document is to be informative, not to keep the reader amused. Also keep in mind that the person reading your document may have learned English as a second language so any use of slang just makes the document harder to read and more confusing for them.
Example:
Next fire up your web browser and navigate to ...
Next start your web browser and navigate to ...
Hey, you sass that hoopy Ford Prefect? There's a frood who really knows where his towel is.
Hey, you know that really together guy Ford Prefect? There's a really amazingly together guy who really has his affairs in order.
Use imperative mood
When providing instructions in a step by step guide use the imperative mood, ie, use direct commands or requests. Avoid the use of "we" and "let's".
Example:
Let's add a shapefile by ...
Add a shapefile by ...
First we will add a shapefile, and then we will create a template for it.
First add a shapefile, and then create a template for it.
Linking
Links to other pages should not be titled as "here". They should be more informative.
More information about adding shapefiles can be found [here].
For more information about adding shapefiles, see the [shapefile tutorial].
Naming conventions
Many of the guidelines in this section are taken from the Wikipedia naming convensions.
Capitalization
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.
Example:
Adding a Shapefile or PostGIS Table
Adding a shapefile or postgis table
Shapefile Tutorial
The Shapefile Tutorial
Section names
Do not capitalize second and subsequent words unless the title is almost always capitalized in English (for example, proper names). Thus, capitalize John Wayne and Art Nouveau, but not Video Games.
Example:
Creating a new datastore
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.
Example:
Creating a new datastore
Create a new datastore
Plurals
In general only create page titles that are in the singular, unless that noun is always in a plural form in English, such as scissors or trousers, or concerns a small class, such as Arabic numerals, polar coordinates, Bantu languages, or The Beatles, that requires a plural.
Example:
Template tutorial
Templates tutorial
Formatting
Code and command line
Any code or command line snippets should be formatted as code.
Example:
This is a code block.
Note: In restructured text this is achieved with the marker ::
Handling long lines in code examples
When lines are longer than 77 characters, extend multiple lines in a format appropriate for the language in use. If possible, snippets should be functional if a user copies and pastes them directly into the appropriate target. For example, Java and XML make no distinction between a single space and multiple spaces, so the following snippets are fine:
org.geoserver.package.Object someVeryLongIdentifier = org.geoserver.package.Object.factoryMethod();
<namespace:tagname attributename="attributevalue" attribute2="attributevalue" nextattribute="this is on another line"/>
For shell scripts, new lines can be escaped with a backslash character (/). It is also recommended to use a simple {{$ }} prompt to save space. For example:
$ /org/jdk1.5.0*/bin/java \
-cp /home/user/.m2/repository/org/geoserver/*/*.jar \
org.geoserver.GeoServer -DGEOSERVER_DATA_DIR=/var/lib/geoserver_data/release
User interface components
When describing a button or link or some other user interface component use monospaced text. When describing input surround it with "quotes"
Example:
Enter "foo" in the Alias text field. Enter "4326" in the SRS text field. Then click the Submit button. Then the Apply button.
Note: In restructured text this monospaced text is accomplished with ``monospaced text``
Commonly misspelled (and incorrectly capitalized) words
The following are words which are frequently either misspelled or capitalized incorrectly.
CamelCase
GeoServer
GeoSearch (except when referring to Google's project "geo search"
GeoTools
GeoWebCache
OpenLayers
PostGIS
Capitalization
No capitalization
coverage
coveragestore
datastore
feature
featuretype
namespace
shapefile (except when using the term "ESRI Shapefile")