Wiki guidelines
The following Wiki guidelines outline a number of suggestions which should ideally be followed when writing wiki pages to help create a useful and easy to use wiki for this rapidly developing project. WikiProject Cleanup is a page coordinating work on the wiki in part to increase conformance with these guidelines.
Contents |
Understandability
Please take into account, that OSM is not only a project of computer-freaks and scientists, but also of mappers. These mappers are possibly bicyclists, hikers, trucker, anglers or other hobbyhorsers. Pages explaining mapping, should be targeted at the wide demographic we are trying to reach out to. Think children and grandmothers! For them the technical details can be confusing.
Some areas of the wiki naturally take the form of technical documentation. Even within technical documentation 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.
Structure
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.
Conflicting information
Conflicting information is very bad. Information about current tagging recommendations should be consistent. Information about proposed changes to tagging can be inconsistent with current tagging and incompatible with other proposed tagging changes, but these pages should clearly be identified as proposals. Tagging recommendations may of course vary from actual tagging practice because there is no requirement within OSM to follow this guidance and the tagging evolves by sometimes breaking rules. When tagging practice diverges significantly from the wiki guidelines it may be appropriate to adjust the wiki to match practice.
Duplication
Duplication is often bad because there is a likelihood that the alternative explanations may vary slightly or significantly in the advice given.
Where there is duplication, it should normally be rationalised to ensure that there is a single clear source of information on each subject. This may require tact and discussion on the relevant talk pages! It is fine to summarise a topic in another page but that summary would link to the main page.
There may be a conscious decision to duplicate some information, where it is being presented in a different style / page structure. In these cases 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 somehow.
Template:merge is used to label pages which require reorganisation to remove duplication. 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 we may decide to leave a summary section on one page, with a link leading to a whole page dedicated to the topic with more detail.
Titles - Page naming convention
We'd like to move towards following Wikipedia capitalising naming conventions: For page titles, use lowercase after the first word, and do not capitalise second and subsequent words, unless the title is a proper noun. For multiword page titles, leave the second and subsequent words in lowercase unless the title phrase is a proper noun that would always occur capitalized, even in the middle of a sentence.
Prefixes within wiki page titles have been used heavily in the past for various types of pages. e.g. the 'WikiProject' prefix. This is mostly a cumbersome legacy, but not one we can easily rectify at this stage. Moving all such pages would be too big a task. However creating new page title prefixing schemes is strongly discouraged. Just use natural language page titles, and cross-link a set of pages to create linking structures in the content of the pages themselves.
Please refer to the Wiki organisation for the current discussion on this topic.
Introduction
Pages should have a good but short introductory paragraph which includes the title in bold and explains in the a few sentences what the page is about. It will often be appropriate to include a link to a more general page and to a few more specific pages to help people navigate to the correct page.
The introductory sentences will 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". Normally this should be restructured so that at least part of the introduction is at the top of the page above any headings. This is just to achieve consistent layout style across the wiki.
Linking
In general wiki pages should be well linked to help people find the information they are looking for. Important related concepts are usually linked within the top description sentences. 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. Obviously throughout the page, you're also encouraged to link related concepts.
Linking a section to a main page
The {{main|page name}} code could be used under a section heading to provide a link to a main page relating to the subject of the section. The section should then only summarise the linked 'main' page (and should certainly not conflict with it in any way). The title for the section should normally be the same as the page to which it is linked.
Wikipedia linking
People often get carried away with linking to wikipedia. Only link to wikipedia if it's useful, and if the concept is not better explained in an OSM context on this wiki.
Wikipedia links can be confusing. If you're using the [[wikipedia:page name]] interwiki syntax, you should generally 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 already found on the site. The page should describe the site in an OSM context. We might also be more neutral and less promotional with our description, although we should always 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.
Example:
- OpenLayers (openlayers.org) - A JavaScript library for showing maps.
In very space constrained situations (often in the case of wiki tables) we might use the numbered link syntax (e.g. [1]) 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.
Categories
Categories should be used to group pages by type which should follow the same naming conventions as with wiki pages.
Categories can themselves be categorised to create a hierarchy to help navigation to the subject of interest. For example Category:Buses is categorised within Category:Public transport.
Pages can be part of a number of categories but should not 'spam' categories. An 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 as well as the more specific one.
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 'Pages relating to [[Public transport]] as an introduction to the category 'Public transport'.
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: [[Category:Users in London|Harry Wood]] with the sort phrase provided after the '|'.
Language
Regarding British English or American English, we are using 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.
Translation
See Wiki Translation. This includes some introductory philosophical thoughts on what we aim to achieve with translations within the wiki.
Date formatting
Dates should be formatted in one of these ways depending on the precision required:
- 12 August 2009 (the normal format, unless there is uncertainty or where the day is highly relevant)
- Wednesday 12 August 2009 (for when the day of the week matters)
- 1 August 2009 (no need for the leading zero in the day value)
- August 2006 (day of month is not known nor relevant)
- 2009
- 'Soon' (August 2009) (when a prediction was made at a particular time)
For preference don't use the following formats:
- 12th August 2009 (ordinal suffixes are not necessary)
- August 12 2009 (keep a consistent order)
- 12 Aug 2009 (Ok, but better to spell month in full?)
- Wed 12 August 2009 (Ok, but possibly better to spell day in full?)
The following phrases which are unclear or go out of date should be avoided:
- 12 August (Which year is that, 2007? 2008? 2009?)
- 12.08.2009 (Is that 12 August 2009 or 08 December 2009?)
- 01 August 2009 (don't include leading zero for day)
- Soon/yesterday/tomorrow etc (replace with a full date or qualify with the date when the phrase was written to 'Soon (as of August 2009)'
- Friday (which Friday?)
- Summer 2009 (summer in the northern hemisphere is winter down south, and winter 2009 in the northern hemisphere can be either December 2009 or January to February 2009)
