OLPC:Style guide: Difference between revisions

From OLPC
Jump to navigation Jump to search
(write on separate lines)
 
(27 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{stub}}
{{wiki-gang}}
'''''This is a work in progress -- please add your comments and suggestions to this page.'''''
<div style="font-size:80%">
{{TOCright}}
{{TOCright}}
</div>
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.
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.


== Languages ==
El Tabaquismo
'''Proposed''': 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]] and this style guide page) may have individual pages translated here on this multilingual site.
: Counterargument: I disagree if you mean completely different wiki's. Multiple languages can co-exist here at OLPC with proper translation and auto translation to fill in the gaps.[[User:Sethwoodworth|Seth]] 21:55, 18 August 2008 (UTC)


== Campaigns and slogans ==
El tabaquismo es una de las principales causas de muerte en el mundo.
# '''One Laptop per Child''' : lowercase 'p'.
Tiene mas de 1000 sustancias toxicas entre ellas el alquitran y la nicotina.
# '''Give One, Get One''' / '''Give 1, Get 1''' / '''give 1, get 1''' : the latter predominated in 2007, moving to the former in 2008.
El tabaquismo es una enfermedad crónica sistémica perteneciente al grupo de las adicciones. Causa enfermedades cardiacas y pulmonares.
# '''give a laptop. change the world.''' and longer version '''give a laptop. get a laptop. change the world.''' for Simply Give and G1G1.
Actualmente se cree la causa principal mundial de enfermedad y mortalidad evitable. Se la considera una enfermedad adictiva crónica con posibilidades de tratamiento.
# [[Change the World]] : the Give 100 and Give 1000 programs in 2008. Two caps, lowercase 'the'

Problemas de salud asociados al tabaquismo

El fumar puede ser el causante de varias enfermedades, como el cáncer de pulmón, la bronquitis tipo R2, el enfisema pulmonar (perforación de los pulmones), y un tipo de gripe dañina por la cual el cerebro puede absorber el agua que ingerimos.

El tabaquismo es reconocido desde hace varios años como un problema de salud pública, debido a que los daños a la salud asociados al consumo del tabaco causan más de medio millón de muertes en el continente americano. El fumar es la causa más frecuente de muertes que pueden evitarse. Según los últimos informes, cientos de miles de personas mueren anualmente de forma prematura debido al tabaco. Estudios recientes indican que la exposición al humo de los cigarrillos fumados por otra gente y otros productos del tabaco, producen al año la muerte de miles de personas que no fuman Pese a estas estadísticas y a numerosos avisos sobre los peligros de fumar, millones de adultos y adolescentes siguen fumando. De todos modos se están haciendo progresos: cada día son más las personas que dejan de fumar.

En el año 2004, la Organización Mundial de la Salud estimaba en 4,9 millones el número de muertes anuales relacionadas con el consumo de tabaco. Pese a existir una probada relación entre tabaco y salud, esto no impide que sea uno de los productos de consumo legal que puede matar al consumidor asiduo.

Fumar un sólo cigarrillo da lugar a una elevación del ritmo cardíaco, la frecuencia respiratoria y la tensión arterial. El humo produce una reacción irritante en las vías respiratorias. La producción de moco y la dificultad de eliminarlo es la causa de la tos. Debido a la inflamación continua se produce bronquitis crónica. También produce una disminución de la capacidad pulmonar, produciendo al fumador mayor cansancio y disminución de resistencia en relación a un ejercicio físico. Cáncer

Determinadas sustancias cancerígenas del humo del tabaco que pasan a la sangre inducen cáncer en varios órganos, principalmente en los pulmones, la laringe y la boca.

Aparato circulatorio

Los efectos del tabaco aumentan la aparición de arteriosclerosis, favoreciendo el desarrollo de trastornos vasculares, cerebrales y cardíacos.

También afecta a los miembros inferiores y puede aparecer la enfermedad vascular periférica.
Fumadores pasivos

Son aquellas personas que no fuman, pero que están en contacto constante con los fumadores e inhalan el humo del cigarro; los fumadores pasivos también pueden contraer problemas en las vías respiratorias.

Dependencia física de la nicotina

No existe hoy día una opinión unánime acerca de la importancia de la dependencia física a la nicotina como mayor o único componente de la adicción. Allen Carr, creador de un conocido método para dejar de fumar, afirmaba que aunque la ansiedad provocada por la retirada de la nicotina es físicamente real, es mucho más leve de lo que aparenta. Por tanto, esta ansiedad, aunque existente, podría estar multiplicada en la mente del fumador por factores sociales, situaciones de estrés o sus propios temores, lo que, de ser cierto, agregaría un componente psicológico muy importante a la adicción física.
Los problemas de salud a los que se exponen quienes son presas de esta enfermedad son innumerables. Destacan los problemas cardiovasculares, como hipertensión y riesgo de ataque cardiaco. También se encuentra el riesgo muy elevado de padecer diferentes tipos de cáncer, donde el de pulmón ocupa el primer lugar, seguido de la laringe y boca, entre otros.
Por otro lado, existe el peligro latente de desarrollar EPOC (enfermedad pulmonar obstructiva crónica), en donde la capacidad respiratoria se va minando poco a poco y de manera irreversible, disminuyendo la calidad de vida de quien la padece de manera dramática.
Otras afecciones muy inconvenientes, son el riesgo de sufrir de colesterol elevado, envejecimiento prematuro de la piel, osteoporosis, manchas en los dientes o caries y mal aliento (halitosis), infertilidad primaria en los hombres, úlcera, gastritis, colitis, bronquitis, así como dificultades durante el embarazo o afecciones en el bebé.
El principal problema es que muchas de estas enfermedades son silenciosas, y no dan aviso hasta que ya han afectado al organismo de manera grave. Se desarrollan muy lentamente, lo que hace que el fumador no se dé cuenta de que está alimentando un padecimiento que en la mayoría de los casos es crónico e irreversible.
Sustancias venenosas
El gran daño que hace el tabaquismo a los fumadores, se explica por la cantidad de sustancias nocivas que componen un cigarrillo. Cada vez que se inhala el humo del tabaco, se introducen al organismo más de cuatro mil sustancias nocivas, entre las que destacan monóxido de carbono, dióxido de carbono, cianuro de hidrógeno, amoniaco y partículas de plomo y arsénico, entre otras.
En cuanto a los tipos de cigarrillos conviene saber esto. Los cigarros lights son más perjudiciales que los normales por dos razones principalmente. En primer lugar, durante su producción se les añade diversos productos químicos que contienen nitrógeno, lo que los hace más dañinos. Además, debido a que tienen un poco menos de nicotina, comúnmente se inhalan de manera mucho más profunda para que cumpla con los requerimientos de esta sustancia, a los que el organismo ya está acostumbrado.
Otro de los penosos y muy injustos aspectos del tabaquismo, es que incluso miles de personas que no fuman, y que se exponen frecuentemente al humo del cigarrillo, llamados fumadores de segunda mano o pasivos también padecen las mismas complicaciones de salud. Debemos de tomar en cuenta, que en cuanto a espacios cerrados, no hay un radio seguro en el que podamos decir que estamos a salvo de las sustancias nocivas del humo.
En este sentido, las “áreas de no fumar” de los sitios públicos no están libres de contaminación por el cigarrillo.
Es muy importante destacar también, sobre todo en aquellos adultos que están iniciando una familia, que son mayores las posibilidades de que los hijos de fumadores se conviertan también en fumadores, y a muy temprana edad. Esto como resultado de la imitación y de la facilidad con la que los niños y adolescentes pueden disponer de cigarros en su propia casa. Las estadísticas se elevan cuando es la madre quien fuma, ya que pasa generalmente más tiempo con los hijos.
Adicionalmente al detrimento de la salud, de la propia y la de los seres cercanos, los costos económicos resultan considerables. Si tan sólo hiciéramos el ejercicio de ver cuánto gastamos en cigarrillos al año, veríamos que podríamos destinar esta cantidad a algún otro rubro que actualmente quizás no podemos considerar dentro de nuestros gastos, como podría ser el pago de un gimnasio, ropa o diversiones.
El mecanismo de la adicción
Alguna vez se ha preguntado, ¿por qué fuma? Y si ya lo ha intentado, ¿por qué es tan difícil dejar de fumar? La razón se encuentra en la nicotina, una de las principales sustancias que componen el tabaco y que es altamente adictiva, incluso más que la cocaína. Al ingresar en el organismo, la nicotina se transporta a lo largo de 300 o 400 millones de alveolos y en menos de 10 segundos llega al cerebro. Aquí, esta sustancia promueve la liberación de dopamina, que es una hormona que normalmente se libera cuando estamos experimentando sensaciones de bienestar, por lo que nos induce a un estado de placer.
Es por esta razón que nos acostumbramos a vivir con esta sensación placentera de manera permanente, y más aún, un cigarrillo se hace imprescindible en los momentos en que nos sentimos inseguros, preocupados, ansiosos o deprimidos, ya que gracias al cigarrillo desaparecen estos factores negativos. El efecto de satisfacción que nos brinda un cigarrillo dura aproximadamente media hora, por lo que la necesidad de mantenernos en un estado de ánimo “elevado”, induce a muchas personas a fumar incluso más de una cajetilla al día.
Por otro lado, el cigarro forma parte de un esquema social, difícil de abandonar. En las reuniones con amigos, donde se comparte vino o café, el cigarrillo llega a formar un elemento imprescindible, que estimula y da seguridad durante la convivencia. Sin éste, el fumador se siente incómodo, y puede tener dificultad incluso para mantener una conversación o asociar ideas.
El principio para dejarlo
Cuando tratamos de dejar de fumar sin ningún tipo de apoyo resulta muy difícil, ya que al suspender el suministro de nicotina al que está fuertemente acostumbrado el cerebro y el organismo, se sufre del casi insoportable síndrome de abstinencia. Éste consiste en sensaciones de irritabilidad, nerviosismo, mal humor, depresión y hasta insomnio y estreñimiento; tan difícil de sobrellevar, que la mayoría de quienes lo sufren prefieren volver a fumar, en lugar de padecer esto.
Por lo tanto, hay que tener muy claro que dejar de fumar no es una cuestión de fuerza de voluntad. Es necesario que a este problema se le considere como una enfermedad que requiere de un tratamiento integral para solucionarlo. Además de la fuerza de voluntad, es necesaria la atención de un médico que evalúe las particularidades de cada fumador, es decir, sus patrones de conducta relacionados con el hábito de fumar, para que establezca un tratamiento dirigido a su caso en particular.
En el caso de un adulto que ha fumado durante 30 o 40 años, su dependencia al cigarrillo es más de tipo físico, pero en el caso de un adolescente, es generalmente de tipo emocional.
Algunos productos que se utilizan como auxiliares para dejar de fumar son las gomas de mascar o parches de nicotina, que sustituyen el suministro de esta sustancia al organismo. Por otro lado, un medicamento muy avanzado para dejar de fumar, y de reciente puesta en el mercado se llama Chantix. Este medicamento actúa produciendo el mismo efecto de satisfacción que la nicotina de cigarrillo, pero moderadamente, lo que ayuda a los fumadores a mantenerse más tiempo sin fumar. De manera complementaria, ofrece la ventaja de reducir los síntomas de ansiedad que se experimentan cuando siendo adicto al cigarro, se suspende el hábito de fumar.
Adicionalmente, si durante el tratamiento se fuma, la sensación que produce el cigarro será muy desagradable, por lo que se abstendrá la persona de fumar.
Lo importante es saber que si ha tomado la decisión de dejar de fumar, no está solo. Hay varias clínicas especializadas para dejar de fumar tan sólo en la Ciudad de México. En éstas se cuenta con personal profesional y capacitado, médicos y psicólogos, principalmente, que podrán apoyarlo para que logre su propósito de una manera exitosa.
Dejar de fumar lo hará sentirse mucho más sano, libre por no depender de una adicción para sentirse bien, con más vitalidad y a salvo de muchas enfermedades que podrían afectar dramáticamente su calidad de vida, o la de las personas más cercanas a usted. El mejor momento para tomar la decisión es éste, no lo deje pasar.


== Project pages ==
== Project pages ==
Line 103: Line 58:
* Avoid capitalizing page titles unless a necessary proper noun. Use [[Content projects]], not [[Content Projects]].
* 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.
* 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.
* The name of an article should [be able to] appear in the first sentence describing its subject. Avoid article names that add extra features to the title, such as "[[Feature Browsing toolkit]]" -- call this [[Browsing toolkit]] and find another way to indicate it is a feature.
** See also ''lead sentence style''... you should mention the article name as early in the first sentence as possible, and mark it in '''bold'''. (Trick: If you make a wiki link to the current article name, it appears in bold &mdash; <nowiki>in this article [[OLPC:Style guide]]</nowiki> appears as [[OLPC:Style guide]].)


=== Redirects ===
=== Redirects ===
Line 111: Line 68:


=== Subpages ===
=== 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:
In general, avoid subpages (??, note how Sugar Labs uses subpages extensively, e.g. [http://wiki.sugarlabs.org/go/0.94/Feature_List 0.94/Feature_List]); 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
* Archives of a page/talk page
* A topic that's too big for one page, e.g. the 2012 [[Help Activity refresh]].
* Subpages for recurring meetings, such as [[OLPC:Volunteer Infrastructure Group/2008-08-17]].
* 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.
* 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.
* 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.

Subpages are often used when a set of hierarchical information is moved to a wiki. In these cases, the articles about that information should be named according to the nouns they describe; and the titles of the pages (see [[#Titles]]) should be mentioned as early in the first sentence of the page as possible. If you can't include the title of an article as written in a sentence, you may want to rename it.

Exceptions to this are usually made for essays and other notes made within user: and project: namespaces.


=== Preparing for the future ===
=== Preparing for the future ===
Line 126: Line 89:


=== Headers ===
=== Headers ===
* '''<big><font color="orange">do NOT use H1 headers</font></big>''' 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.
* '''<big><font color="orange">do NOT use H1 headers</font></big>''' 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 [[{{FULLPAGENAME}}]] above); any further H1's should indicate the inclusion of an entire other page. Imagine what happens when you [http://en.wikipedia.org/wiki/Transclusion 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.

H1 headers should be reserved for the page's title (like this page's [[{{FULLPAGENAME}}]] above); any further H1's should indicate the inclusion of an entire other page. Imagine what happens when you [http://en.wikipedia.org/wiki/Transclusion 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.
** 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.

* As with article titles, only capitalize the first letter of the first word unless using proper nouns, for example <nowiki>==Upcoming community events</nowiki>, not <nowiki>==Upcoming Community Events</nowiki>.


=== Categorization ===
=== Categorization ===
Line 138: Line 101:


Category names are usually plural &mdash; things in the category are [[:Category:Activities|activities]], [[:Category:Countries|countries]], [[:Category:Messaging ideas|messaging ideas]], etc.
Category names are usually plural &mdash; things in the category are [[:Category:Activities|activities]], [[:Category:Countries|countries]], [[:Category:Messaging ideas|messaging ideas]], etc.
And category titles should follow [[#Titling a new article]] conventions, thus "Category:Spanish '''d'''eployment'''s'''", not "Category:Spanish Deployment".


== Writing ==
== Writing ==
Line 148: Line 112:
* Avoid long strings of adjectives or nouns.
* Avoid long strings of adjectives or nouns.
* Convert sentences in unusual tenses into ones in simple tenses with extra clarifying notes.
* Convert sentences in unusual tenses into ones in simple tenses with extra clarifying notes.

=== Write for posterity: avoid "currently", and date "will" ===
Wiki pages live forever. Every time you write, for example:
: The content translation program, for which there is currently no organization...<br />These software packages currently depend on Orbit...<br />TamTam will feature 2 different tools...
you mislead future readers, and you make it nearly impossible for editors to tell if a page is out of date.

* Unless the page's title is tied to a particular date, like "Meeting #3 notes" or "Curriculum Jam Fall 2007", <br />''don't use "currently" or "will" or any other phrase tied to a point in time'', unless you '''date''' your statement with '''As of August 2008, ...'''


=== Keep words clear and unique ===
=== Keep words clear and unique ===
Line 154: Line 125:


=== Specific words ===
=== Specific words ===
; USB flash drive
; "[[USB drive]]" or "USB flash drive"
: "USB key" is confused with cryptographic concepts such as [[developer key]].
: "USB key" is confused with cryptographic concepts such as [[developer key]], "stick" and "thumb" are non-standard.

; first "Browse Activity", then just "Browse"
: Activities aren't commands and are more than programs. So the first time a page or chapter mentions an activity, say "the Read Activity". Thereafter you can simply say "Read".

=== Write for easy editing ===
In normal paragraphs,
MediaWiki does line breaking and forms paragraphs for you,
so you can start each concept on a new line.
Some old advice applies:
: First, when you do the purely mechanical operations of typing, type so subsequent editing will be easy. Start each sentence on a new line. Make lines short, and break lines at natural places, such as after commas and semicolons, rather than randomly. Since most people change documents by rewriting phrases and adding, deleting and rearranging sentences, these precautions simplify any editing you have to do later.<br />''— Brian W. Kernighan, 1974''
This also when seeing what changed in a page, as the History tab shows changes to lines.

== Obsolete and deprecated information ==
This wiki is stuffed with information from 2007 before there was final hardware, an official release, and any consensus on what/when/where/how OLPC would do things.
This mass of outdated information makes the wiki harder to maintain, search, and understand.

If you think a page might be obsolete, mark it so at the top something like
: ''Information is from 2007 and seems out-of-date, compare with [[Foo]]''

If you're sure a page is obsolete,
* insert {{tl|obsolete}} at the top:<br />
<nowiki>{{obsolete|link=[[better page]]}}</nowiki>
* consider removing most of its <nowiki>[[Category:Foos]]</nowiki> annotations so obsolete pages don't show up in categories.
* click the obsolete page's [What links here] in the navigation and replace links to it with [[better page]]

Once nothing links to the page, mark it with the {{tl|delete}} template
<nowiki>{{delete|2007 info no longer applies, nothing
important links here, replaced by [[better page]]}}</nowiki>

=== Pre 8.2 information ===
As of December 2008, [[Release notes/8.2.0|Release 8.2.0]] is the latest stable release.
However, many [[G1G1 2007]] recipients have not upgraded, and some [[G1G1 2008]] recipients are receiving laptops with [[Release notes/8.1.0|Release 8.1.0]] installed.
We encourage users to upgrade to the latest release, {{tl|Consider upgrading}} is a template that makes this recommendation.

So pages should start with the 8.2.0 information, then mention earlier behavior:
: In [[Release notes/8.2.0|Release 8.2.0]], xyz ''works like this''
: In releases prior to 8.2.0, xyz ''worked like this''<br><nowiki>{{Consider upgrading}}</nowiki>
You should eliminate info that only applies to releases prior to [Release notes/7.1.0|Release 7.1.0]] ("ship.2", build 653).


== Using advanced features ==
== Using advanced features ==
Line 169: Line 178:


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

=== Semantic annotations ===
This wiki has the Semantic MediaWiki and Semantic Forms extensions.
These let you annotate information in wiki pages so you can browse it and other pages can query it.
See [[Semantic MediaWiki]] for the pages using it, and cautions.


== Visual design of pages ==
== Visual design of pages ==

Latest revision as of 20:53, 15 April 2012

   This page is part of the Wiki Cleanup Project.   [[ Wiki SEO | Cleanup | Wiki tasks ]]

This is a work in progress -- please add your comments and suggestions to this page.

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.

Languages

Proposed: 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 and this style guide page) may have individual pages translated here on this multilingual site.

Counterargument: I disagree if you mean completely different wiki's. Multiple languages can co-exist here at OLPC with proper translation and auto translation to fill in the gaps.Seth 21:55, 18 August 2008 (UTC)

Campaigns and slogans

  1. One Laptop per Child : lowercase 'p'.
  2. Give One, Get One / Give 1, Get 1 / give 1, get 1 : the latter predominated in 2007, moving to the former in 2008.
  3. give a laptop. change the world. and longer version give a laptop. get a laptop. change the world. for Simply Give and G1G1.
  4. Change the World : the Give 100 and Give 1000 programs in 2008. Two caps, lowercase 'the'

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.

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.
  • The name of an article should [be able to] appear in the first sentence describing its subject. Avoid article names that add extra features to the title, such as "Feature Browsing toolkit" -- call this Browsing toolkit and find another way to indicate it is a feature.
    • See also lead sentence style... you should mention the article name as early in the first sentence as possible, and mark it in bold. (Trick: If you make a wiki link to the current article name, it appears in bold — in this article [[OLPC:Style guide]] appears as OLPC:Style guide.)

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, avoid subpages (??, note how Sugar Labs uses subpages extensively, e.g. 0.94/Feature_List); 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
  • A topic that's too big for one page, e.g. the 2012 Help Activity refresh.
  • Subpages for recurring meetings, such as OLPC:Volunteer Infrastructure Group/2008-08-17.
  • 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.

Subpages are often used when a set of hierarchical information is moved to a wiki. In these cases, the articles about that information should be named according to the nouns they describe; and the titles of the pages (see #Titles) should be mentioned as early in the first sentence of the page as possible. If you can't include the title of an article as written in a sentence, you may want to rename it.

Exceptions to this are usually made for essays and other notes made within user: and project: namespaces.

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.
  • As with article titles, only capitalize the first letter of the first word unless using proper nouns, for example ==Upcoming community events, not ==Upcoming Community Events.

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. And category titles should follow #Titling a new article conventions, thus "Category:Spanish deployments", not "Category:Spanish Deployment".

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.

Write for posterity: avoid "currently", and date "will"

Wiki pages live forever. Every time you write, for example:

The content translation program, for which there is currently no organization...
These software packages currently depend on Orbit...
TamTam will feature 2 different tools...

you mislead future readers, and you make it nearly impossible for editors to tell if a page is out of date.

  • Unless the page's title is tied to a particular date, like "Meeting #3 notes" or "Curriculum Jam Fall 2007",
    don't use "currently" or "will" or any other phrase tied to a point in time, unless you date your statement with As of August 2008, ...

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 drive" or "USB flash drive"
"USB key" is confused with cryptographic concepts such as developer key, "stick" and "thumb" are non-standard.
first "Browse Activity", then just "Browse"
Activities aren't commands and are more than programs. So the first time a page or chapter mentions an activity, say "the Read Activity". Thereafter you can simply say "Read".

Write for easy editing

In normal paragraphs, MediaWiki does line breaking and forms paragraphs for you, so you can start each concept on a new line. Some old advice applies:

First, when you do the purely mechanical operations of typing, type so subsequent editing will be easy. Start each sentence on a new line. Make lines short, and break lines at natural places, such as after commas and semicolons, rather than randomly. Since most people change documents by rewriting phrases and adding, deleting and rearranging sentences, these precautions simplify any editing you have to do later.
— Brian W. Kernighan, 1974

This also when seeing what changed in a page, as the History tab shows changes to lines.

Obsolete and deprecated information

This wiki is stuffed with information from 2007 before there was final hardware, an official release, and any consensus on what/when/where/how OLPC would do things. This mass of outdated information makes the wiki harder to maintain, search, and understand.

If you think a page might be obsolete, mark it so at the top something like

Information is from 2007 and seems out-of-date, compare with Foo

If you're sure a page is obsolete,

 {{obsolete|link=[[better page]]}}
  • consider removing most of its [[Category:Foos]] annotations so obsolete pages don't show up in categories.
  • click the obsolete page's [What links here] in the navigation and replace links to it with better page

Once nothing links to the page, mark it with the {{delete}} template

 {{delete|2007 info no longer applies, nothing
          important links here, replaced by [[better page]]}}

Pre 8.2 information

As of December 2008, Release 8.2.0 is the latest stable release. However, many G1G1 2007 recipients have not upgraded, and some G1G1 2008 recipients are receiving laptops with Release 8.1.0 installed. We encourage users to upgrade to the latest release, {{Consider upgrading}} is a template that makes this recommendation.

So pages should start with the 8.2.0 information, then mention earlier behavior:

In Release 8.2.0, xyz works like this
In releases prior to 8.2.0, xyz worked like this
{{Consider upgrading}}

You should eliminate info that only applies to releases prior to [Release notes/7.1.0|Release 7.1.0]] ("ship.2", build 653).

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.

Semantic annotations

This wiki has the Semantic MediaWiki and Semantic Forms extensions. These let you annotate information in wiki pages so you can browse it and other pages can query it. See Semantic MediaWiki for the pages using it, and cautions.

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.

Article and visual flow

Use of color

External links