Openmoko Wiki Editing Guidelines

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Application info pages section added)
m (Application info pages: no screenshot info/image added.)
Line 105: Line 105:
 
== Application info pages ==
 
== 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.  
 
Software available for Openmoko smartphones are collected on special list pages and categories to make it easy to find.  
  
Line 113: Line 114:
 
* [[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.
 
* [[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]].
 
* Add a link to the application page on [[Applications]].
 +
* Use this image if you don't have a screenshot.
  
 
== Style Sheet ==
 
== Style Sheet ==

Revision as of 22:54, 30 September 2008

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.


Contents

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

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

Text editing

These pages explain how to write and format text:

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

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

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.

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

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

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.

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, 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.8
      • (according to William Lai [1])(the third version of the distribution)
  • P
  • Q
  • R
  • S
  • T
  • U
  • V
  • W
  • X
  • Y
  • Z

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.

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

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

Text editing

These pages explain how to write and format text:

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

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

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.

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

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

Application info pages

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:

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, 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.8
      • (according to William Lai [1])(the third version of the distribution)
  • P
  • Q
  • R
  • S
  • T
  • U
  • V
  • W
  • X
  • Y
  • Z

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.

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.