OLPC:Style guide

From OLPC
Revision as of 13:52, 18 July 2007 by Xavi (talk | contribs) (some notes on templates and page transclusion)
Jump to navigation Jump to search

Welcome to the OLPC Wiki style guide. See Guidelines for a human interface 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.

Article naming

Starting a new article

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.

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 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.

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.

Headers

  • avoid using h1 headers within a page (a single equals on each side),

since h1 headers should be reserved for the page title. 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.

Categorization

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

Advanced features

Templates

Are special pages intended to be transcluded in other pages producing some result based on the 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.

Templates should be tagged with the <noinclude>[[Category:Template]]</noinclude> or one of its subcategories.

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.

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