The following Wiki guidelines should be followed when writing wiki pages. This will help create a useful and easy to use wiki, that is accessable to everyone. WikiProject Cleanup is a page coordinating work on the wiki in part to increase conformance with these guidelines.
Focus on usability
Create new perspectives when necessary
Big pages and categories with too many items are equally harmful/useless/hard to read/hard to maintain.
Use simple language when possible
Keep pages short, use simple language and avoid jargon. OpenStreetMap aims to be accessible to all, and our documentation should reflect this. Aim your writing at the level of children and grandmothers!
Some wiki pages naturally take the form of technical documentation. Even within these we should aim to be understandable to users with a range of technical abilities. Write simple introductions to lead into a topic, and consider splitting off very complex details to separate more focussed wiki pages.
Don't overuse this rule: by creating simplified versions of the text you actively preventing other users from learning complex topics. To avoid this, explain complex topic in simple terms and using real terminology
Pages should start with a short introductory paragraph comprising a few sentences. This should includes the title in bold and explain what the page is about. It's often useful to include a link to a more general page and to any more specific pages, as this helps navigation.
This introductory section should appear before any headings (and before the Table of Contents on a long page). Note that it is fairly common for people to create a first heading "Introduction". This should be restructured so that at least part of the introduction is at the top of the page above any headings. This will achieve a consistent layout across the wiki.
The wiki should be arranged to allow people to easily find the content they are looking for starting from the Main Page. Some key content is linked directly from the Main Page, but other main page links take you to 'start pages' on a particular topic. They are the next level in a kind of navigation hierarchy. They are often short pages with many links and not too much text (also known as 'portals'). Work is needed to ensure that this navigation is still working effectively for new visitors.
Use /subpages to describe things from various POV will ease wiki maintenance tasks and simplify work for translators and probably help readers. Examples:
Optionally you can hide slash by using following syntax:
Consider meaningful anchors
They might be necessary to deduplicate content and point readers at precise position. Templates will help you:
Please try to avoid them / don't overuse them, consider page split and rewrite with more meaningful headings. Page with heading is simpler to maintain and to translate.
Conflicting information is very bad. Information about current tagging recommendations should be consistent. If this is not the case please get in touch with other users to develop a consensus. Tagging recommendations should ideally match actual tagging practice, unless there is a valid reason not to do so.
Proposals and proposed changes to tagging are the exeption to this rule. They must however be clearly be identified as proposals.
Duplication is often bad because it risks providing conflicting information and increases the amount of work. Where there is unnecessary duplication, it should be rationalised to provide a single clear source of information. This may require discussion with other users! It is fine to summarise a topic in another page but that summary would link to the main page.
Template:merge is used to label pages which require reorganisation to remove duplication.
Where duplication is useful (for example, it is being presented in a different style, page structure, or for differing audiences), it is important to be clear about the reasoning for this, and cross-link to avoid confusion. If there is no good reason for duplication, then the pages should be merged. Note that a merge does not necessarily mean we are left with one page where there were two before. There are other outcomes, for example a non-technical summary page page may link to a more detailed technical page.
Categories should be used to group pages by type which should follow the same naming conventions as with wiki pages.
A single line introduction should be provided for every category which should in general link to an appropriate 'main' page for the subject, ideally of the same name. For example
When being categorised, pages should use the sort order option if necessary to ensure that they appear appropriately in the list of pages. For instance look at the pages listed in Category:Users in London. They would all be listed under 'U' because of the 'User:' prefix, but this has been overridden. For example the User:Harry Wood has the category wiki text:
Don't copy categories when creating temporary content or translating in your user pages
Otherwise your unfinished user page will appear in English category.
Over categorization is still actual for OSM wiki
Pages can be part of a number of categories but should not 'spam' categories. A page relating to buses (for example, a page about bus stops) should be categorised as 'Buses' but not also as 'Public transport'. However, the main Buses page should be tagged within the 'Public transport' category. Please create navigational templates using navbox template.
To avoid over categorization but also to provide cross-links to other useful pages user might want to create Templates using Template:Navbox and place them at each page. See Template:Highways and Template:DE:Highways for reference.
Good example what not to do with categories:
Pages should be well linked to help users find the information they are looking for. Important related concepts are usually linked to within the introduction. If you can't think of a related wiki page to link from here, then you're probably not describing the page in broad enough terms. You are also encouraged to link to related concepts throughout the rest of the page.
Linking a section to a main page
Wikipedia links can be confusing. Only link to wikipedia if it's useful, and if the concept is not better explained in an OSM context on this wiki.
If using the [[wikipedia:page name]] interwiki syntax, please leave the 'wikipedia:' prefix in place i.e. Don't do alternate link text: [[wikipedia:page name|page name]] as this is hugely confusing in a basic navigational sense. Don't link to a wikipedia page where the same or similar title exists on this wiki.
Page about a website
We have lots of wiki pages dedicated to describing some external website (map services, software products etc). Obviously the external link to that site is hugely important. The main link should be placed in brackets after the title (which is bold) in the very first sentence and/or linked in larger text on it's own line after the top descriptive sentences.
On these pages there is no point duplicating lots of 'about' information found on the external site. The page should describe the site in an OSM context. Be more neutral and less promotional with your description, although do aim to use language which promotes OSM and uses of OSM.
Listing software / services
We have a number of pages containing bullet pointed lists or wiki tables listing software / services. If we have wiki pages about the software, or even if we haven't (red links) the preferred format is an internal link to the OSM wiki page followed by an external link to the site in brackets. This might then be followed by a short description or other table columns. We should aim to provide links to both the wiki page and the external link even where the wiki page doesn't exist yet to encourage a healthy level of wiki interlinking. Red links can be filled in with stub information following the advice above.
Full URL external links can be nice, if they are short, since the user knows what to expect when they click it. Alternate link text should be used to shorten this, preferably to the domain name so that it's still clear that this is an external link.
In very space constrained situations (often in the case of wiki tables) we might use the numbered link syntax (e.g. ) to shrink the external link right down. We might opt to drop the external link and only link the wiki page, since this will itself have the external link. If the wiki page doesn't exist we might opt to only provide an external link, but it might be better to create a wiki page with stub description.
Internationalization and language-specific perspective
OpenStreetMap uses British English for general English pages and the appropriate 'local' English for localised topic pages. So any page which mostly concerns the U.S., for whatever reason, would use American English. This particularly applies to place pages under Mapping projects.
See Wiki Translation. This includes some introductory philosophical thoughts on what we aim to achieve with translations within the wiki, while it's not clear whether the wiki will migrate to the Translate extension.
Dates should be formatted in one of these ways depending on the precision required:
Ordinal suffixes (th, nd, rd) are not necessary, and days and months should be written out in full. Avoid incomplete dates that are unclear, and avoid the use of seasons (summer in the northern hemisphere is winter down south!).