OLPC:Style guide

This article is a stub. You can help the OLPC project by expanding it.

Welcome to the OLPC Wiki style guide. This is here to keep people from creating pages with strange wikisemantics and titles and categorizations that don't naturally help other wiki users find them. Or lead to edit wars that continue across centuries.

Language

Pages in different languages should be on their own wikis -- one wiki per language. Languages that do not yet have a few introductory pages in their language (including the Main Page, OLPC:About, a village pump for discussions and this style guide page) may hvae individual pages translated here on this multilingual site.

Project pages

Projects

see Activities and Activities/tmp

This is a description of sections, format, and style that are helpful in creating a project page that others can use and contribute to.

Collections and library/reading activities

• ...

Software and interactive activities

• ...

Data and other basic collections

• Sound samples, sets of clipart
• Software libraries, to be used by other software collections
• Icon collections to be used to customize one's interface

Organizations

Pages about organizations introduce the group, and should describe its engagement in education, connected digital networks, and access to knowledge, in all relevant languages.

Partners and the like

• ...

Community groups and local chapters (see also #Regions below)

• ...

Volunteers] and community members

• ...

Regions

Articles about regional groups should describe the region and the groups and organizations in them, and the extent of deployments, educational efforts, and user groups in that region. They should link to specific pages for each regional chapter or user group. The general page about OLPC efforts in South Carolina, for instance, should be South Carolina, not OLPC South Carolina (which may exist if an organized group using that name exists; in the case of Illinois for instance that group would be ILXO rather than OLPC Illinois).

Article naming

Starting a new article

The article you're about to write already exists in the 20,000+ pages here: use the search box, also Google search, and browse Special:Categories to find it.

• Always check for alternative capitalizations — if you're starting Content Projects, check for Content projects first.

Titling a new article

Use a title that others will find and use.

• Avoid capitalizing page titles unless a necessary proper noun. Use Content projects, not Content Projects.
• Similarly, avoid running words together in CamelCase unless you are referring to a proper noun such as MediaWiki. This makes it easier to link words used normally in a sentence.

Redirects

On a similar note to Article naming, it's a good idea to make redirects to alternative capitalizations and common typos of page names. For instance, if you're starting Content projects, make redirects to Content Projects, Contentprojects, etc. (But there's no need for content projects; due to MediaWiki's automatic capitalization of the first letter, this goes to the same place as Content projects.)

Similarly, if you find yourself looking for a wikipage and assuming it's under another name which turns out to be a nonexistent page, redirect that page to the correct one when you find it. For instance, if you're looking for what eventually turns out to be Content projects and find, while looking along the way, that Projects for content is empty, redirect that page to Content projects.

Subpages

In general, subpages are to be avoided -- better to use a descriptive name which can be read out without a 'slash' somewhere in it. However, there are exceptions:

• Archives of a page/talk page
• Dated versions of the same page ... though these should usually be without subpages as well, unless they are dated versions of large subsites, which only link to one another. For instance, if we were to make a "2006" version of Localization/www.laptop.org, that might go under Localization/2006/www.laptop.org... since there are many other pages that go along with it.
• Subpages of user pages for half-finished notes, scratchwork, testing, and semi-private projects - although if it's at the point where other people can begin to understand and contribute to it, move it out of your user space into the main wiki area.

Preparing for the future

If you are starting a specific type of page and know that you will need to make general versions later, that's fine -- use the most generic name that is not already taken. likewise, if you are starting the "August 2007" version of a page, leave it at the general name until you have more than one instance, at which point you can start to move to archival page titles. This just helps ensure that any specific page-name is part of an ecology that includes more generic page names and overviews of the abstract topic at hand.

Links, classification, and structure

Links to other articles

Links can be listed in full, in which case you should replace any underscores in the link with a space. For instance, Style guide should not have an underscore — even though Style_guide links to the same page, the underscore is ugly.

MediaWiki links are case sensitive. However, MediaWiki will find a linked article regardless of the capitalization of its first letter. This feature lets you include page links in sentence flow, e.g. Join friends in testing to try out recent builds.

Headers

• do NOT use H1 headers within a page (i.e., don't do =Header with a single equals on each side=). Start your hierarchy with ==H2 level header== within the body of the wiki article.

H1 headers should be reserved for the page's title (like this page's OLPC:Style guide above); any further H1's should indicate the inclusion of an entire other page. Imagine what happens when you transclude one page at the end of another: this should make sense within a Table of Contents if you add an H1 header before it.

• • although this is a valid point, other wikis have solved it by adjusting header levels when transcluding. E.g. if a page is including at an H4 level, then any H1 heading in that page is mapped to H4, and so on.

Categorization

Every page should belong to a category (multiple categorization is possible) so when creating or editing pages, try to find a good one.

You should never create a new category until you have located at least two pages to put in that category. Edit the new category's page to explain briefly its intent and any templates that categorize in it. When you create a new category, add it to existing categories so the category itself is discoverable.

Category names are usually plural — things in the category are activities, countries, messaging ideas, etc.

Writing

Write for translation

See also Guidelines for writing for eventual translation for a more detailed description of guidelines.

Keep sentences simple:

• Avoid idioms and extended metaphors. Where metaphors are particularly useful, try to use one that is universal and has no double-meanings.
• Avoid subclauses or long sentences.
• Avoid long strings of adjectives or nouns.
• Convert sentences in unusual tenses into ones in simple tenses with extra clarifying notes.

Keep words clear and unique

• Avoid words with ambiguous meanings.
• Long words with clear roots can be better than short words that are obscure or have many connotations

Specific words

USB flash drive

"USB key" is confused with cryptographic concepts such as developer key.

Using advanced features

Templates

Are special pages intended to be invoked from other pages producing some result based on parameters provided or extracted from the including page. A template that just transcludes static text is not a template and should be treated as normal page. There's the Template:Sandbox to try new ideas on templates.

Always add a <noinclude> purpose... Usage ...</noinclude> block explaining the purpose of the template.

Templates should be tagged with the Category:Template or one of its subcategories within the <noinclude> block

Page transclusion

The composing of an article based on other pages is a very powerful idea but that can quickly get out of hand as interdependencies develop (not to mention the complication for future editors to actually find the right page to edit). Still, it's a powerful (and sometimes complicated) way to reuse context in several places.

If a page is intended for transclusion in other pages, you should probably put any categorization or semantic annotation in it within a <noinclude>...</noinclude section, otherwise every page that transcludes it will get categorized and annotated.

Visual design of pages

Some of the principles in the HIG apply across the board. For instance, walter is unhappy with the insertion of navigational elements (or is it just visual attractions?) in the middle of a page; see template talk:support-nav for a recent discussion.

External links

• From useit.com, ca. 2002