Help:Style
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 =.
|
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:
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:
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.
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
- 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 textor<pre>long output text</pre> - Description: Describe the result of an entered command.
- Where: Anywhere
Meeting transcripts
- 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
- Help:Editing on Wikipedia