8,288
edits
Changes
Wiki Team/Guide/Style Guide (view source)
Revision as of 20:10, 16 March 2009
, 20:10, 16 March 2009no edit summary
=Introduction=
==Introduction==
The pages in this wiki should be as easy to understand and follow as possible. With this in mind, please take into account the following suggested writing style guidelines:
The pages in this wiki should be as easy to understand and follow as possible. With this in mind, please take into account the following suggested writing style guidelines:
=Terminology=
==Terminology==
*Sugar releases - Always try to specify which versions of Sugar a page is valid for. When referring to Sugar releases, use "Sugar X.XX" - eg. "Sugar 0.82".
*Sugar releases - Always try to specify which versions of Sugar a page is valid for. When referring to Sugar releases, use "Sugar X.XX" - eg. "Sugar 0.82".
*Linux distributions - Capitalize the names of Linux distributions like Fedora, Debian, Ubuntu, etc.
*Linux distributions - Capitalize the names of Linux distributions like Fedora, Debian, Ubuntu, etc.
*Operating Systems - Capitalize the names of operating systems like Linux, Ubuntu, Windows, etc.
*Operating Systems - Capitalize the names of operating systems like Linux, Ubuntu, Windows, etc.
=Page Titles=
==Page Titles==
* Be descriptive.
* Be descriptive.
* Avoid using the word "Howto" in the page title (everything here is a howto!).
* Avoid using the word "Howto" in the page title (everything here is a howto!).
* Avoid camel casing, such as 'WikiTeam', because search engines will not find this 'Team', so 'Wiki Team', then. (We are in the process of converting away from CamelCase contractions, so you may see many examples of the deprecated style.)
* Avoid camel casing, such as 'WikiTeam', because search engines will not find this 'Team', so 'Wiki Team', then. (We are in the process of converting away from CamelCase contractions, so you may see many examples of the deprecated style.)
=Section Headings=
==Section Headings==
* '''do NOT use H1 headers''' within a page (''i.e.,'' don't do =Header with a single equal signs 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.
*: 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.
*:: Even if the structure problems are moot, the extra large typeface in the H1 header may be considered 'too loud', like shouting in the context of the smaller typefaces on the rest of the page and sidebars. Notice that it seems more appropriate for a single use to title the page.
(Taken from the GNOME Style Guide)
* Heading text should be short, clear, and descriptive.
* Heading text should be short, clear, and descriptive.
* Capitalize in the following manner:
* Capitalize in the following manner:
** All lowercase letters for conjunctions, articles, and prepositions of less than four letters
** All lowercase letters for conjunctions, articles, and prepositions of less than four letters
=Lists=
==Lists==
Bullet lists of links should take the following form: <Bullet> <Link> <Hyphen> <Sentence>.
Bullet lists of links should take the following form: <Bullet> <Link> <Hyphen> <Sentence>.
* For example:
* For example:
** Skype - Internet telephony software (closed source).
** Skype - Internet telephony software (closed source).