Openmoko Wiki Editing Guidelines

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Revise wiki editing instructions re categories.)
(Undo revision 82082 by Demver5 SPAM)
 
(38 intermediate revisions by 10 users not shown)
Line 1: Line 1:
Our Openmoko Wiki Editing Guidelines are meant to assist our users in editing this wiki.  They try to ensure a somewhat more consistent and organized structure.
+
{{Languages|Openmoko_Wiki_Editing_Guidelines}}
  
 +
Our Openmoko Wiki Editing Guidelines are meant to assist our users in editing this wiki. They try to ensure a somewhat more consistent and organized structure. If you would like to add additional guidelines or to modify existing ones please use the [https://lists.openmoko.org/mailman/listinfo/documentation documentation mailing list] or the [[Talk:Openmoko Wiki Editing Guidelines|talk page]] to discuss your changes first.
  
 
== Naming ==
 
== Naming ==
  
# Openmoko is only referring to pure Software (think Openmoko GNU/Linux distribution)
+
# Openmoko refers only to the software (think Openmoko GNU/Linux distribution), not to any of the devices
# Neo 1973 is the first hardware device that officially runs Openmoko
+
# Neo 1973 is the first hardware device that officially runs Openmoko, Neo FreeRunner is the second
 
# Use "the smartphone" if you refer to a hardware device that could be Neo 1973 but could also be a later version
 
# Use "the smartphone" if you refer to a hardware device that could be Neo 1973 but could also be a later version
  
 
== Rules ==
 
== Rules ==
  
# If you're adding information (esp. Pages) about the Hardware, keep in mind that the Neo 1973 is only one of the various devices that will run Openmoko. Thus,
+
# If you see an error, correct it!
## Do not create generic pages like "Battery", rather use "Neo 1973 Battery"
+
# If you see a page that is mis-categorized, correct it!
## If it makes sense to have generic pages, use per-device sections and make sure you always link to the Neo 1973 section from other Neo 1973 specific pages
+
# If you're adding information (especially pages) about the hardware, keep in mind that the Neo 1973 is only one of the various devices that will run Openmoko. Thus,
## See [http://wiki.openmoko.org/wiki/Help:Contents#A_list_of_definitive_spellings_used_throughout_the_site| this] page for a list of other definitive spellings used in the Openmoko project
+
## Do not create generic pages like "Battery", rather use "Neo 1973 Battery".
 +
## If it makes sense to have generic pages, use per-device sections and make sure you always link to the Neo 1973 section from other Neo 1973 specific pages.
 +
## See [[Openmoko_Wiki_Editing_Guidelines#Style Sheet|Style sheet]] section for a list of other definitive spellings used in the Openmoko project.
 
# The wiki is primarily meant to contain factual information on actual project software, hardware, even though parts might still be under development. Thus,
 
# The wiki is primarily meant to contain factual information on actual project software, hardware, even though parts might still be under development. Thus,
## If you're adding information about wishlist items (or even more imaginary things), please clearly mark them with a "Wishlist:" prefix in the page title.
+
## If you're adding information about wishlist items (or even more imaginary things), please clearly mark them with a "Wishlist:" prefix in the page title.
 
## Always make sure that an outside user can clearly distinguish between the actual feature set of the device, and "interesting theoretical plans of what one could do if he had time" :)
 
## Always make sure that an outside user can clearly distinguish between the actual feature set of the device, and "interesting theoretical plans of what one could do if he had time" :)
 +
# Avoid duplication! Multiple sources often get out of sync, leading to confusion and mis-information. If you have new information see if it is an appropriate addition to an existing page. If you do feel that a new page is in order, remove duplicated information from the existing page and consolidate in your new page.
 +
# Use categories! We are trying to use categories as a way to help newcomers find what they want. Proper categorization of your new page or any existing pages will help bring your valuable information to the eyes of the user, and will help raise the level of usefulness of the entire wiki
  
== Adding a new page ==
+
== Text editing ==
  
To start a new page you can either create a link to it first on another page, like this:  
+
These pages explain how to write and format text:
  
<nowiki>[[My new page]]</nowiki>
+
* [http://meta.wikimedia.org/wiki/Help:Wikitext_examples MediaWiki Wikitext Examples]
 +
* [[Help:Editing]]
 +
* [http://www.crockford.com/wrrrld/style.html Elements of Style]. Knowing these 18 rules of good style is a must for anybody writing in English.
 +
* [http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style Wikipedia's Manual of Style]
  
then click the resulting link and start editing the new page, or you can add your new page name to the URL in your browser's address-bar, like this:
+
== Use categories ==
  
<nowiki>http://wiki.openmoko.org/wiki/My_new_page</nowiki>
+
Adding categories to a page allows the wiki engine to organize the content automagically. This allows readers to find information in an organized way.
  
and create the page first, before linking to it, or allow the wiki nannies to do the linking for you... they will see your page show up here:
+
* Add a category at the bottom of the pages you create, select the most-accurate category for the page.
 +
* If a page truly fits in multiple categories, OK, but the wiki will be more organized if you pick the one most-accurate category only.
 +
* Review the existing category hierarchy on the [[:Category:Categories]] page. (Be sure to press the + buttons to see the subcategories.)
 +
* A [[Special:Categories|complete list of all categories]] is also available.
  
http://wiki.openmoko.org/wiki/Special:Recentchanges
+
Assigning your page to categories:
  
== Use categories ==
+
<pre>
 +
  [[Category:My selected category]]
 +
  [[Category:My new category]]
 +
</pre>
  
Adding [[Special:Categories | categories]] to a page allows the wiki engine to organize the content automagically. This allows readers to find information in an organized way.
+
=== Image categorization ===
  
* Please add a category at the bottom of the pages you create, trying to select the one most-accurate category for the page.
+
All images used in this wiki should be in a subcategory of [[:Category:images]]
* If a page truly fits in multiple categories, OK, but the wiki will be more organized if you pick the one most-accurate category.
+
* Review the existing category list on the [[Special:Categories | categories]] page. (Be sure to press the + buttons to see the subcategories.)
+
* If a category does not exist and you think a new one is required then use the same category syntax to create a new one.
+
  
To add your page to a category:
+
=== Creating new categories ===
 +
 
 +
If a category does not exist and you think a new one is required then add your page to the not-existing category as described above.
 +
 
 +
Be sure to click on the new category link and define what you were thinking should go into this category by editing the '''category page'''. Please be brief so readers will easily see the automatically indexed page links below your introduction text.
  
 
<pre>
 
<pre>
  [[Category:My selected category]]
+
{{Languages|:Category:My new category}}
  [[Category:My new category]]
+
 
 +
Category description
 +
 
 +
[[Category:Parent category]]
 
</pre>
 
</pre>
  
If you are creating a new category, then be sure to click on the new category link and define what you were thinking should go into this category. Please be brief so readers will easily see the automatically indexed page links below your introduction text.
+
=== Linking to a category page ===
  
 
To link to a category page within the page text:
 
To link to a category page within the page text:
 +
 
<pre>
 
<pre>
 
   [[:Category:My new category | My new category]]
 
   [[:Category:My new category | My new category]]
Line 56: Line 75:
  
 
For more help on categories, please see [http://www.mediawiki.org/wiki/Help:Categories MediaWiki's "Categories" help page.]
 
For more help on categories, please see [http://www.mediawiki.org/wiki/Help:Categories MediaWiki's "Categories" help page.]
 +
 +
== Use templates ==
 +
 +
Please see available [[Templates]] and add them where necessary.
 +
 +
=== Navigation templates ===
 +
 +
Exemples: [[Template:Om_2008.8]], [[Template:OM2007.2]]
 +
 +
These are most useful to present small sets of chronological or otherwise
 +
well ordered information items. For example, it's obvious to offer navigation
 +
templates between these articles:
 +
* Openmoko produced smartphones {GTA01 Neo 1973, GTA02 Neo FreeRunner, GTA 03
 +
(speculative)}
 +
* Distributions {2007.1, 2007.2, 2008.8 ASU, 2008.9, FSO, SHR, Qtopia, Debian}
 +
 +
In effect navigation templates create a subset of important pages presented sequentially. This corresponds more or less to a chapter in the user manual. We should not force them where they cannot create a CONSISTENT  forth-and-back navigation between a GROUP OF PAGES.
 +
 +
See also: http://en.wikipedia.org/wiki/Wikipedia:Navigation_templates
 +
 +
== Fill the "Edit Summary" field ==
 +
Many wiki editors do not fill in "Edit Summary" filed under "edit" box. This summary becomes very handy when it comes to later version comparision. Always fill in "edit summary" field when editing wiki pages. All you need to type there are 3~4 words of comment, and really makes life easier for wiki administrators.
 +
It's a good idea to set your user preferences (under Editing) to "Prompt me when entering a blank edit summary". If you really want to keep it empty, you can just confirm the message or enter a blank space to avoid the message.
 +
It is also quick and quite good habit to prefix summary with +/-/= depending upon you add/delete/edit content.
 +
 +
== Deleting pages ==
 +
 +
Pages in this wiki can only be deleted by the wiki administrators. There are two ways for requesting the deletion of a page:
 +
 +
===Speedy deletion===
 +
 +
Speedy deletion can be requested if the deletion of a page is uncontroversial - for example if a page contains information that is not related to Openmoko. This process is similar to Wikipedia's [http://en.wikipedia.org/wiki/Wikipedia:Criteria_for_speedy_deletion speedy deletion]. In order to request a speedy deletion of a page, place the template <nowiki>{{delete-sp}}</nowiki> somewhere on the page. This will categorize the page in [[:Category:candidates for speedy deletion]].
 +
 +
===Deletion discussion===
 +
 +
If the reason for deletion of a page is not obvious you can initiate a deletion discussion. This process is similar to Wikipedia's [http://en.wikipedia.org/wiki/Wikipedia:Articles_for_deletion Articles for deletion]. It requires two steps:
 +
 +
*place the template <nowiki>{{delete}}</nowiki> on the top of the page you'd like to delete
 +
*Start a discussion at [[Wiki Issues#Pages proposed for deletion]] by giving your reasons for the proposal
 +
 +
The discussion must be open for at least two weeks. If there is a consensus on deleting the page it will be deleted by an administrator. Otherwise the page will be kept. In both cases the discussion will be moved to the page [[Wiki Issues/archive]].
 +
 +
== List pages ==
 +
 +
List pages are manually maintained lists of links to a certain set of articles. Their purpose is similar to category pages' automatic article listing, but they can provide advantages above the automatic lists, like sections, better formatting, sorting, etc.
 +
 +
A list page is only justified if it gives value added to the reader by
 +
* Making a thematic selection of quality links within and/or outside the Wiki
 +
* Providing a well thought out logical organization that makes it easy to  find information
 +
* Offering a good formatting consistent with the above goal. List pages should be not be painful to maintain. Comprehensive lists of pages cannot be kept up to date and are better made automatically using categories.
 +
 +
You are welcome to create and improve list pages which match these recommendations.
 +
 +
See also: http://en.wikipedia.org/wiki/Wikipedia:Categories,_lists,_and_navigation_templates
 +
 +
==Special pages==
 +
 +
These guidelines are for special pages from one of the following categories.
 +
 +
=== Application info pages ===
 +
 +
[[Image:No-screenshot.png|150px|right]]
 +
Software available for Openmoko smartphones are collected on special list pages and categories to make it easy to find.
 +
 +
When you add or find an a page describing a single application always:
 +
 +
* Assign the application page to the corresponding [[:Category:Applications|application category]].
 +
* Add an ApplicationBox Template to it. Usage is described on the [[Template talk:ApplicationBox|ApplicationBox template's talk page]].
 +
* [[Template talk:ApplicationBox|Transclude]] (that's a Wiki expression to include a page or section in another page) the ApplicationBox on one of the "List of x Applications" pages.
 +
* Add a link to the application page on [[Applications]].
 +
* Use this image if you don't have a screenshot.
 +
 +
=== Community updates ===
 +
 +
The community updates (CU) are released every two weeks. Each community update starts as a draft at the page "Community Updates/Draft YYYY-MM-DD" where the date is the release date of the community update. On the day of release the Community Updates can be moved to "Community Updates/YYYY-MM-DD" (use the "move" icon at the top for this).
 +
 +
'''Structure''': Each community update usually consists of four sections: '''Distributions''', '''Applications''', '''Community''' and '''Event News''' (See [[Community Update Draft]] for an example)
 +
 +
The section '''Distributions''' is for announcing new versions of a distribution. Please use the standardized [[Template:DistributionBox]] for this purpose.
 +
 +
The section '''Applications''' has got two subsections, '''New Applications''' and '''Application Updates'''. You can use [[Template:ApplicationBox]] for this.
 +
 +
The section '''Community''' usually contains all other information of the past two weeks.
 +
 +
'''Event News''' lists upcoming events about Openmoko.
 +
 +
=== Manuals ===
 +
 +
All information on using phones or distributions should be included in the manuals, which should be subpages of the [[Manuals]] page.
 +
 +
The Manuals are organized in two categories: device-manuals and distribution-manuals. Device-manuals (e.g. [[Manuals/Neo FreeRunner]]) contain any instructions that are specific to a certain device, while distribution-manuals (e.g. [[Manuals/Om 2008]]) contain only information on a certain distribution.
 +
 +
Rules:
 +
* Only include information on how to USE a certain phone/distribution - general information on phones/distributions should be located on other pages.
 +
* Use as few links as possible: If there is a term that needs explanation, try to do this in the manual.
 +
 +
For distribution-manuals:
 +
 +
*As the distributions are still under development the manuals may be helpful by presenting important known issues and how to fix them. If you want to add a notification about an issue to the manual, always add an URL to a bug report for the problem. For example (this was a problem in SHR, it's just an example and it is fixed now):
 +
 +
:"Please note that the standard SHR alarm application does not work if the phone is suspended. You can fix this problem by installing ffalarms. ([http://shr-project.org/trac/ticket/543 bug report])"
 +
 +
:If there is no bug report yet you will have to create one. Reported problems which do not link to a bug report or link to a closed bug report should/can be deleted.
 +
 +
* In the distribution manuals there should only be instructions for applications which are preinstalled on this distribution. If you want to write a manual about an application which is not preinstalled on the distribution you may create a seperate manual for that application or use the application page.
 +
 +
 +
==Linking to mailing list posts==
 +
 +
Often there is a need to provide link pointing to discussion on a mailing list. Services providing web interface to mailing lists (like nabble.com) were [http://lists.openmoko.org/pipermail/community/2009-June/050363.html reported] many times to break discussion threads in mail clients. Remember, mailing lists were designed to be used with mail clients, not with web forums. The Openmoko mailing list archives at http://lists.openmoko.org are not recommended either because they change the URL to a certain topic sometimes and so links may lead to the wrong post after some time. If you need to provide a link to a discussion on the mailinglist for those who are not subscribed, use mailing list archives like gmane:
 +
* Go to [http://news.gmane.org/index.php?prefix=gmane.comp.handhelds.openmoko gname]
 +
* choose a mailing list
 +
* From the top panel choose a post (preferably the one on the top of a thread)
 +
* At the bottom panel click "Subject:" link
 +
* Copy the URL from your browser
  
 
== Style Sheet ==
 
== Style Sheet ==
 +
=== Date format ===
 +
All dates should be in the [http://en.wikipedia.org/wiki/ISO_8601 ISO_8601] standard: YYYY-MM-DD, for example 2008-07-04 for July 4 2008.
 +
 
=== A list of definitive spellings used throughout the site ===
 
=== A list of definitive spellings used throughout the site ===
 +
 
* Numbers [0-9]
 
* Numbers [0-9]
 
** 1973  
 
** 1973  
***(the model name of the first OpenMoko phone)
+
***(the model name of the first Openmoko phone)
 
*A
 
*A
  
Line 74: Line 212:
 
*F
 
*F
 
** FreeRunner  
 
** FreeRunner  
***(not freerunner or Freerunner)
+
***(not Freerunner)
***(the model name of the 2nd OpenMoko phone)
+
***(the model name of the 2nd Openmoko phone, technically GTA02)
 
*G
 
*G
  
Line 93: Line 231:
 
*N
 
*N
 
** Neo
 
** Neo
*** (the brand name of OpenMoko phones)
+
*** (the brand name of Openmoko phones)
 
** Neo 1973
 
** Neo 1973
*** (the brand and model name of the first OpenMoko phone)
+
*** (the brand and model name of the first Openmoko phone)
*** (not neo1973 or neo 1973.  Note this has changed during the course of the project and a lot of current entries in the Wiki and software are wrong.  See [[http://lists.openmoko.org/pipermail/community/2008-February/013136.html | here]] for the official pronouncement as of Feb08)
+
*** (not neo1973 or neo 1973.  Note this has changed during the course of the project and a lot of current entries in the Wiki and software are wrong.  See [http://lists.openmoko.org/pipermail/community/2008-February/013136.html here] for the official pronouncement as of February 2008)
 
** Neo FreeRunner  
 
** Neo FreeRunner  
*** (the brand and model name of the second OpenMoko phone)
+
*** (the brand and model name of the second Openmoko phone)
 
*** (not NeoFreeRunner or neo freerunner)
 
*** (not NeoFreeRunner or neo freerunner)
  
 
*O
 
*O
** Openmoko  
+
** "Openmoko" or "Om"
 
*** (the name of the complete software stack)
 
*** (the name of the complete software stack)
*** (not "OpenMoko" anymore as of [http://www.businesswire.com/portal/site/home/?newsLang=en&viewID=news_view_popup&epi-content=NEWS_VIEW_POPUP_TYPE&beanStrID=reportcenterndm&newsId=20080304005158 March 2008].   Note this change means many current entries in the Wiki are wrong - please help to amend!)
+
*** (not "OpenMoko" anymore as of [http://www.businesswire.com/portal/site/home/?newsLang=en&viewID=news_view_popup&epi-content=NEWS_VIEW_POPUP_TYPE&beanStrID=reportcenterndm&newsId=20080304005158 March 2008].)
 
** Openmoko Inc
 
** Openmoko Inc
 
*** (the name of the Taiwanese company that develops products for the project)
 
*** (the name of the Taiwanese company that develops products for the project)
Line 111: Line 249:
 
** openmoko.com
 
** openmoko.com
 
*** (the commercial website and webshop of Openmoko Inc)
 
*** (the commercial website and webshop of Openmoko Inc)
 +
** Om 2007.2
 +
*** (the second version of the Openmoko distribution)
 +
** Om 2008
 +
*** (the third version of the distribution)
 +
** Om 2009
 +
*** (the fourth version of the distribution)
 
*P
 
*P
  
Line 133: Line 277:
 
*Z
 
*Z
  
== Follow your own pages ==
+
== Follow up on your own pages ==
  
 
When you create a new page, it's a good idea to add it to your watchlist. Check your watchlist regularly to keep up with the evolution of the pages you have created, help the new editors of your page.
 
When you create a new page, it's a good idea to add it to your watchlist. Check your watchlist regularly to keep up with the evolution of the pages you have created, help the new editors of your page.
  
 +
== See also ==
  
{{Languages|Openmoko_Wiki_Editing_Guidelines}}
+
See also sections are for linking to other '''related articles in this Wiki'''. For external links please create an '''External links''' section instead. We encourage adding see also links to pages.
 +
 
 +
* [[Edit Wiki]]
 +
* [[Wiki Issues]]
  
[[Category:Help]]
+
[[Category:Wiki Editing]]
[[Category:Information| ]]
+

Latest revision as of 10:24, 19 August 2010


Our Openmoko Wiki Editing Guidelines are meant to assist our users in editing this wiki. They try to ensure a somewhat more consistent and organized structure. If you would like to add additional guidelines or to modify existing ones please use the documentation mailing list or the talk page to discuss your changes first.

Contents

[edit] Naming

  1. Openmoko refers only to the software (think Openmoko GNU/Linux distribution), not to any of the devices
  2. Neo 1973 is the first hardware device that officially runs Openmoko, Neo FreeRunner is the second
  3. Use "the smartphone" if you refer to a hardware device that could be Neo 1973 but could also be a later version

[edit] Rules

  1. If you see an error, correct it!
  2. If you see a page that is mis-categorized, correct it!
  3. If you're adding information (especially pages) about the hardware, keep in mind that the Neo 1973 is only one of the various devices that will run Openmoko. Thus,
    1. Do not create generic pages like "Battery", rather use "Neo 1973 Battery".
    2. If it makes sense to have generic pages, use per-device sections and make sure you always link to the Neo 1973 section from other Neo 1973 specific pages.
    3. See Style sheet section for a list of other definitive spellings used in the Openmoko project.
  4. The wiki is primarily meant to contain factual information on actual project software, hardware, even though parts might still be under development. Thus,
    1. If you're adding information about wishlist items (or even more imaginary things), please clearly mark them with a "Wishlist:" prefix in the page title.
    2. Always make sure that an outside user can clearly distinguish between the actual feature set of the device, and "interesting theoretical plans of what one could do if he had time" :)
  5. Avoid duplication! Multiple sources often get out of sync, leading to confusion and mis-information. If you have new information see if it is an appropriate addition to an existing page. If you do feel that a new page is in order, remove duplicated information from the existing page and consolidate in your new page.
  6. Use categories! We are trying to use categories as a way to help newcomers find what they want. Proper categorization of your new page or any existing pages will help bring your valuable information to the eyes of the user, and will help raise the level of usefulness of the entire wiki

[edit] Text editing

These pages explain how to write and format text:

[edit] Use categories

Adding categories to a page allows the wiki engine to organize the content automagically. This allows readers to find information in an organized way.

  • Add a category at the bottom of the pages you create, select the most-accurate category for the page.
  • If a page truly fits in multiple categories, OK, but the wiki will be more organized if you pick the one most-accurate category only.
  • Review the existing category hierarchy on the Category:Categories page. (Be sure to press the + buttons to see the subcategories.)
  • A complete list of all categories is also available.

Assigning your page to categories:

  [[Category:My selected category]]
  [[Category:My new category]]

[edit] Image categorization

All images used in this wiki should be in a subcategory of Category:images

[edit] Creating new categories

If a category does not exist and you think a new one is required then add your page to the not-existing category as described above.

Be sure to click on the new category link and define what you were thinking should go into this category by editing the category page. Please be brief so readers will easily see the automatically indexed page links below your introduction text.

{{Languages|:Category:My new category}}

Category description

[[Category:Parent category]]

[edit] Linking to a category page

To link to a category page within the page text:

  [[:Category:My new category | My new category]]

For more help on categories, please see MediaWiki's "Categories" help page.

[edit] Use templates

Please see available Templates and add them where necessary.

[edit] Navigation templates

Exemples: Template:Om_2008.8, Template:OM2007.2

These are most useful to present small sets of chronological or otherwise well ordered information items. For example, it's obvious to offer navigation templates between these articles:

  • Openmoko produced smartphones {GTA01 Neo 1973, GTA02 Neo FreeRunner, GTA 03

(speculative)}

  • Distributions {2007.1, 2007.2, 2008.8 ASU, 2008.9, FSO, SHR, Qtopia, Debian}

In effect navigation templates create a subset of important pages presented sequentially. This corresponds more or less to a chapter in the user manual. We should not force them where they cannot create a CONSISTENT forth-and-back navigation between a GROUP OF PAGES.

See also: http://en.wikipedia.org/wiki/Wikipedia:Navigation_templates

[edit] Fill the "Edit Summary" field

Many wiki editors do not fill in "Edit Summary" filed under "edit" box. This summary becomes very handy when it comes to later version comparision. Always fill in "edit summary" field when editing wiki pages. All you need to type there are 3~4 words of comment, and really makes life easier for wiki administrators. It's a good idea to set your user preferences (under Editing) to "Prompt me when entering a blank edit summary". If you really want to keep it empty, you can just confirm the message or enter a blank space to avoid the message. It is also quick and quite good habit to prefix summary with +/-/= depending upon you add/delete/edit content.

[edit] Deleting pages

Pages in this wiki can only be deleted by the wiki administrators. There are two ways for requesting the deletion of a page:

[edit] Speedy deletion

Speedy deletion can be requested if the deletion of a page is uncontroversial - for example if a page contains information that is not related to Openmoko. This process is similar to Wikipedia's speedy deletion. In order to request a speedy deletion of a page, place the template {{delete-sp}} somewhere on the page. This will categorize the page in Category:candidates for speedy deletion.

[edit] Deletion discussion

If the reason for deletion of a page is not obvious you can initiate a deletion discussion. This process is similar to Wikipedia's Articles for deletion. It requires two steps:

The discussion must be open for at least two weeks. If there is a consensus on deleting the page it will be deleted by an administrator. Otherwise the page will be kept. In both cases the discussion will be moved to the page Wiki Issues/archive.

[edit] List pages

List pages are manually maintained lists of links to a certain set of articles. Their purpose is similar to category pages' automatic article listing, but they can provide advantages above the automatic lists, like sections, better formatting, sorting, etc.

A list page is only justified if it gives value added to the reader by

  • Making a thematic selection of quality links within and/or outside the Wiki
  • Providing a well thought out logical organization that makes it easy to find information
  • Offering a good formatting consistent with the above goal. List pages should be not be painful to maintain. Comprehensive lists of pages cannot be kept up to date and are better made automatically using categories.

You are welcome to create and improve list pages which match these recommendations.

See also: http://en.wikipedia.org/wiki/Wikipedia:Categories,_lists,_and_navigation_templates

[edit] Special pages

These guidelines are for special pages from one of the following categories.

[edit] Application info pages

No-screenshot.png

Software available for Openmoko smartphones are collected on special list pages and categories to make it easy to find.

When you add or find an a page describing a single application always:

  • Assign the application page to the corresponding application category.
  • Add an ApplicationBox Template to it. Usage is described on the ApplicationBox template's talk page.
  • Transclude (that's a Wiki expression to include a page or section in another page) the ApplicationBox on one of the "List of x Applications" pages.
  • Add a link to the application page on Applications.
  • Use this image if you don't have a screenshot.

[edit] Community updates

The community updates (CU) are released every two weeks. Each community update starts as a draft at the page "Community Updates/Draft YYYY-MM-DD" where the date is the release date of the community update. On the day of release the Community Updates can be moved to "Community Updates/YYYY-MM-DD" (use the "move" icon at the top for this).

Structure: Each community update usually consists of four sections: Distributions, Applications, Community and Event News (See Community Update Draft for an example)

The section Distributions is for announcing new versions of a distribution. Please use the standardized Template:DistributionBox for this purpose.

The section Applications has got two subsections, New Applications and Application Updates. You can use Template:ApplicationBox for this.

The section Community usually contains all other information of the past two weeks.

Event News lists upcoming events about Openmoko.

[edit] Manuals

All information on using phones or distributions should be included in the manuals, which should be subpages of the Manuals page.

The Manuals are organized in two categories: device-manuals and distribution-manuals. Device-manuals (e.g. Manuals/Neo FreeRunner) contain any instructions that are specific to a certain device, while distribution-manuals (e.g. Manuals/Om 2008) contain only information on a certain distribution.

Rules:

  • Only include information on how to USE a certain phone/distribution - general information on phones/distributions should be located on other pages.
  • Use as few links as possible: If there is a term that needs explanation, try to do this in the manual.

For distribution-manuals:

  • As the distributions are still under development the manuals may be helpful by presenting important known issues and how to fix them. If you want to add a notification about an issue to the manual, always add an URL to a bug report for the problem. For example (this was a problem in SHR, it's just an example and it is fixed now):
"Please note that the standard SHR alarm application does not work if the phone is suspended. You can fix this problem by installing ffalarms. (bug report)"
If there is no bug report yet you will have to create one. Reported problems which do not link to a bug report or link to a closed bug report should/can be deleted.
  • In the distribution manuals there should only be instructions for applications which are preinstalled on this distribution. If you want to write a manual about an application which is not preinstalled on the distribution you may create a seperate manual for that application or use the application page.


[edit] Linking to mailing list posts

Often there is a need to provide link pointing to discussion on a mailing list. Services providing web interface to mailing lists (like nabble.com) were reported many times to break discussion threads in mail clients. Remember, mailing lists were designed to be used with mail clients, not with web forums. The Openmoko mailing list archives at http://lists.openmoko.org are not recommended either because they change the URL to a certain topic sometimes and so links may lead to the wrong post after some time. If you need to provide a link to a discussion on the mailinglist for those who are not subscribed, use mailing list archives like gmane:

  • Go to gname
  • choose a mailing list
  • From the top panel choose a post (preferably the one on the top of a thread)
  • At the bottom panel click "Subject:" link
  • Copy the URL from your browser

[edit] Style Sheet

[edit] Date format

All dates should be in the ISO_8601 standard: YYYY-MM-DD, for example 2008-07-04 for July 4 2008.

[edit] A list of definitive spellings used throughout the site

  • Numbers [0-9]
    • 1973
      • (the model name of the first Openmoko phone)
  • A
  • B
  • C
  • D
  • E
  • F
    • FreeRunner
      • (not Freerunner)
      • (the model name of the 2nd Openmoko phone, technically GTA02)
  • G
  • H
  • I
  • J
  • K
  • L
  • M
    • MokoMakefile (and it's not a script)
  • N
    • Neo
      • (the brand name of Openmoko phones)
    • Neo 1973
      • (the brand and model name of the first Openmoko phone)
      • (not neo1973 or neo 1973. Note this has changed during the course of the project and a lot of current entries in the Wiki and software are wrong. See here for the official pronouncement as of February 2008)
    • Neo FreeRunner
      • (the brand and model name of the second Openmoko phone)
      • (not NeoFreeRunner or neo freerunner)
  • O
    • "Openmoko" or "Om"
      • (the name of the complete software stack)
      • (not "OpenMoko" anymore as of March 2008.)
    • Openmoko Inc
      • (the name of the Taiwanese company that develops products for the project)
    • openmoko.org
      • (the community, non-commercial website for the project)
    • openmoko.com
      • (the commercial website and webshop of Openmoko Inc)
    • Om 2007.2
      • (the second version of the Openmoko distribution)
    • Om 2008
      • (the third version of the distribution)
    • Om 2009
      • (the fourth version of the distribution)
  • P
  • Q
  • R
  • S
  • T
  • U
  • V
  • W
  • X
  • Y
  • Z

[edit] Follow up on your own pages

When you create a new page, it's a good idea to add it to your watchlist. Check your watchlist regularly to keep up with the evolution of the pages you have created, help the new editors of your page.

[edit] See also

See also sections are for linking to other related articles in this Wiki. For external links please create an External links section instead. We encourage adding see also links to pages.

Personal tools

Our Openmoko Wiki Editing Guidelines are meant to assist our users in editing this wiki. They try to ensure a somewhat more consistent and organized structure.


Naming

  1. Openmoko is only referring to pure Software (think Openmoko GNU/Linux distribution)
  2. Neo 1973 is the first hardware device that officially runs Openmoko
  3. Use "the smartphone" if you refer to a hardware device that could be Neo 1973 but could also be a later version

Rules

  1. If you're adding information (esp. Pages) about the Hardware, keep in mind that the Neo 1973 is only one of the various devices that will run Openmoko. Thus,
    1. Do not create generic pages like "Battery", rather use "Neo 1973 Battery"
    2. If it makes sense to have generic pages, use per-device sections and make sure you always link to the Neo 1973 section from other Neo 1973 specific pages
    3. See this page for a list of other definitive spellings used in the Openmoko project
  2. The wiki is primarily meant to contain factual information on actual project software, hardware, even though parts might still be under development. Thus,
    1. If you're adding information about wishlist items (or even more imaginary things), please clearly mark them with a "Wishlist:" prefix in the page title.
    2. Always make sure that an outside user can clearly distinguish between the actual feature set of the device, and "interesting theoretical plans of what one could do if he had time" :)

Adding a new page

To start a new page you can either create a link to it first on another page, like this:

[[My new page]]

then click the resulting link and start editing the new page, or you can add your new page name to the URL in your browser's address-bar, like this:

http://wiki.openmoko.org/wiki/My_new_page

and create the page first, before linking to it, or allow the wiki nannies to do the linking for you... they will see your page show up here:

http://wiki.openmoko.org/wiki/Special:Recentchanges

Use categories

Adding categories to a page allows the wiki engine to organize the content automagically. This allows readers to find information in an organized way.

  • Please add a category at the bottom of the pages you create, trying to select the one most-accurate category for the page.
  • If a page truly fits in multiple categories, OK, but the wiki will be more organized if you pick the one most-accurate category.
  • Review the existing category list on the categories page. (Be sure to press the + buttons to see the subcategories.)
  • If a category does not exist and you think a new one is required then use the same category syntax to create a new one.

To add your page to a category:

  [[Category:My selected category]]
  [[Category:My new category]]

If you are creating a new category, then be sure to click on the new category link and define what you were thinking should go into this category. Please be brief so readers will easily see the automatically indexed page links below your introduction text.

To link to a category page within the page text:

  [[:Category:My new category | My new category]]

For more help on categories, please see MediaWiki's "Categories" help page.

Style Sheet

A list of definitive spellings used throughout the site

  • Numbers [0-9]
    • 1973
      • (the model name of the first OpenMoko phone)
  • A
  • B
  • C
  • D
  • E
  • F
    • FreeRunner
      • (not freerunner or Freerunner)
      • (the model name of the 2nd OpenMoko phone)
  • G
  • H
  • I
  • J
  • K
  • L
  • M
    • MokoMakefile (and it's not a script)
  • N
    • Neo
      • (the brand name of OpenMoko phones)
    • Neo 1973
      • (the brand and model name of the first OpenMoko phone)
      • (not neo1973 or neo 1973. Note this has changed during the course of the project and a lot of current entries in the Wiki and software are wrong. See [| here] for the official pronouncement as of Feb08)
    • Neo FreeRunner
      • (the brand and model name of the second OpenMoko phone)
      • (not NeoFreeRunner or neo freerunner)
  • O
    • Openmoko
      • (the name of the complete software stack)
      • (not "OpenMoko" anymore as of March 2008. Note this change means many current entries in the Wiki are wrong - please help to amend!)
    • Openmoko Inc
      • (the name of the Taiwanese company that develops products for the project)
    • openmoko.org
      • (the community, non-commercial website for the project)
    • openmoko.com
      • (the commercial website and webshop of Openmoko Inc)
  • P
  • Q
  • R
  • S
  • T
  • U
  • V
  • W
  • X
  • Y
  • Z

Follow your own pages

When you create a new page, it's a good idea to add it to your watchlist. Check your watchlist regularly to keep up with the evolution of the pages you have created, help the new editors of your page.