Home Wiki > Help:Style
Sign up | Login

Help:Style

tagline: From openSUSE

Template:Wiki guidelines nav

These guidelines cover essentials on how to create or edit articles to ensure a consistent look and feel throughout. They are based on similar Wikipedia guidelines.
Working DRAFT

General usability

Neutral style

Use a neutral writing style. Avoid the use of personal pronoun "I", "We", etc.

Keep it short and concise

When writing, consider how quickly you decide to read on, or not. Poorly written and overly wordy articles will not be read.

  • Do not add irrelevant or redundant content. People will read short, clear articles that give the information they need. But they will flee those bloated with irrelevant content.
  • Use a consistent, non-cluttered format from top to bottom. No one will read a lengthy article broken into sections by miss-matched layouts or colors. Those just make reading slower and serve to drive away the reader.
  • To make your article useful and popular, keep it short and concise!

See Article development on Wikipedia.


Structure

Title

  • Title should be clear and short.
  • Do not use cryptic Acronyms, unless sure they are widely know by the target audience.
  • Do not use CamelCase. Instead, use spaces.
  • Use the same capitalization style as Wikipedia.
  • Do not use a colon as separator in titlesas it is used to designate namespace in MediaWiki.
  • Avoid the use of special characters. Use [a-z][A-Z][0-9] characters only.

Section title

  • All above title guidelines apply to section titles also.
  • Since section titles form the table of contents a short telegraphic style aids readability and page navigation.
  • Do not repeat article title in the first section. Redundancy does not encourage further reading.
  • Do not use About or Introduction as name of the first section. First section of any article is introduction in a topic, so telling that explicitly doesn't bring anything new to the reader.

Headings

  • Use the = markup to create a heading. This way, the table of contents is automatically generated from the headings and that helps readers to go directly to the section of interest.
  • Start with double equal sign == not a single =.
Icon-forbidden.png
Forbidden
single equal sign (=) produces the same text size as the article title, which is not used in any common writing style.
  • Do not put links in headings. Instead, link the word or phrase the first time it appears in the section.
  • Split very long section into few subsections using subheadings.
  • Use ---- markup to create a horizontal separator before any level 2 heading (==), as this helps in smooth reading of the article
Example:
 ==heading 1==
 ===subheading 1.1===
 ===subheading 1.2===
 
 ----
 ==heading 2==
 ===subheading 2.2===
 ====subheading 2.2.1====
 =====subheading 2.2.1.1=====

 ----
 ==heading 3==

Content

openSUSE spelling

  • openSUSE is the only correct way to spell openSUSE. "OpenSUSE", "openSuSE", OpenSuse" and other variations are all wrongly formatted.
  • Do not use trademark characters (such as © or ®) as this impedes the article reading.
  • Note that the spelling "SuSE Linux" and "SUSE Linux" are deprecated. Unless referring explicitly to an older release of openSUSE (10.1 and earlier release) for historical purposes, SUSE Linux Enterprise Server (SLES) or SUSE Linux Enterprise Desktop (SLED), use "openSUSE".

Duplication

Do not duplicate effort.

  • Check the openSUSE list of HOWTOs. There is already a large collection of articles. If one exist that covers the subject that you wish to write about then take time to read it and see if it can be improved.
  • The openSUSE forum has a collection of HOWTOs in the Advanced How To/FAQ (read only), forum and another less mature sub-forum Unreviewed How To and FAQ which may present a foundation you can build on.
  • There is also a large collection of HOWTO articles on The Linux Documentation Project.

Acronyms and abbreviations

  • When introducing new acronyms in an article, use the full name on its first occurrence followed by the abbreviated form inside round brackets. For example: Section titles automatically form the table of contents (TOC).
  • Avoid complex abbreviations as they make articles more difficult to read.
  • Always use standard and widely understood abbreviations as innovation may lead to wrong interpretation

Variables

Sometimes, a command input is specific to the user's system, such as system devices or username. Following conventions are to be used:

  • <username>, for example in path command /home/<username>
  • sdX for devices

Please note that:

  • Using such convention usually will require a note like: "Substitute the actual device/username (sda, sdb, hda, etc) in the place of sdX".
  • If multiple devices are discussed use the convention sdX, sdY, sdZ. If more than three devices need to be addressed. just begin with device sdN where is N is the last N letters of the alphabet.

New user safety

Warning: Be especially careful giving instructions that have to be run with root user privileges. Commands like dd, rm, fdisk, can do a lot of damage if used without understanding. New users often don't understand, but just copy and paste command:

  • Do not use example code which if copied and pasted directly into a command line interface will result in a disaster. For example, this command:
# dd if=openSUSE-11.2-KDE4-LiveCD-i686.iso of=/dev/sda

if copied directly to command line will overwrite user first hard disk. The /dev/sda is first hard disk and it exists in every computer, whereas this command:

# dd if=openSUSE-11.2-KDE4-LiveCD-i686.iso of=/dev/sdX

is safe since it is highly unlikely that /dev/sdX exists and therefore an error will be returned (rather than overwriting sda).

Images

Placement

See Image markup for recommendations on the best markup to use. For ideas and examples of how to place images, see Picture tutorial.

Format

  • Drawings, icons and other such images (basically those with large, simple, and continuous blocks of color) should be in PNG format.
  • Photos should be in JPEG format.
  • Animations should be in animated GIF format.
Please note that old versions of articles do not show corresponding old versions of images, but the latest ones, unless the file names of the images have changed.

Comments

  • Do not clutter article text with editorial comments/questions. Instead, use the article's discussion page.
  • If you want to communicate with other editors, make comments invisible to the ordinary article reader by using comment tags.
 <!-- This is an invisible comment.  --> 

Wanted pages

To indicate that there is a need for some article that doesn't yet exist, create a link to the needed article in the text of an existing article. If there are at least two links to the same nonexistent article, it will be listed on Wanted Pages, which is a source of inspiration for many new wiki authors. While not everything there is really needed, common sense and your expertise will tell you which to choose from the list.


Elements

When writing, ensure to use the following convention.

Wiki markup

While it is possible to use HTML tags to format a page, using the MediaWiki markup will make source text easier to read and edit. You may also look at the Wiki Reference card and the source code of a few articles.

Command keys

F5 and Tab

  • Code: <code>Button to press</code>
  • Description: Keyboard button to press.
  • Where: Anywhere

Command path

/usr/src/linux and /etc/SuSE-release

  • Code: <tt>/path/to/directory/or/file</tt>
  • Description: Directory path and file path description.
  • Where: Anywhere

Command input

$ user command
# root command
  • Code: <div class="shell">$ user command</div> or <div class="shell"># root command</div>
  • Description: Command to enter.
  • Where: Anywhere

Command output

output text
  • Code: (blank space)short output text or <pre>long output text</pre>
  • Description: Describe the result of an entered command.
  • Where: Anywhere

Meeting transcripts

... Content ...
  • Code: <div class="minutes"> ... Content ... </div>
  • Description: Display of meeting transcripts.
  • Where: Anywhere

Tables

Heading 1 Heading 2 Heading 3 Heading 4 Heading 5 Heading 6
Highlighted text Highlighted text Highlighted text Text Text Highlighted text
Text Text Text Text Text Highlighted text
Text Text Text Text Text Highlighted text
  • Code: See page source.
  • Description: Display a table with optionally highlighted text.
  • Where: Anywhere

Templates

See Template Guidelines.


See also


External links