Wiki Team/Guide/Style Guide

From Sugar Labs
Jump to navigation Jump to search

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:

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

Page Titles

  • Be descriptive.
  • Avoid using the word "Howto" in the page title (everything here is a howto!).
  • Use capital letters and avoid dashes.
  • 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

  • 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 Wiki Team/Guide/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.
    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.
  • Capitalize in the following manner:
    • Initial uppercase letter for the first word and the last word, regardless of part of speech
    • Initial uppercase letter for all nouns, adjectives, and verbs
    • Initial uppercase letter for conjunctions of four letters or longer
    • Initial uppercase letter for prepositions of four letters or longer
    • Initial uppercase letter for prepositions that are part of a phrasal verb
    • All lowercase letters for conjunctions, articles, and prepositions of less than four letters

Lists

Bullet lists of links should take the following form: <Bullet> <Link> <Hyphen> <Sentence>.

  • For example:
    • Skype - Internet telephony software (closed source).

Punctuation

Retrieved from "https://wiki.sugarlabs.org/index.php?title=Wiki_Team/Guide/Style_Guide&oldid=72258"