LQWiki:Manual of Style

This manual of style is meant to serve as a guideline to help ensure that LQ Wiki articles have a consistent look and feel. It is just a guideline, but consistency will make the wiki easier to read, easier to use and easier to contribute to. Clear, informative and unbiased writing is always more important than presentation and formatting. Remember, one of the great things about a wiki is that perfection is not required. Don't let this article stop you from plunging forward. Other wiki users will find your article when weeding and all articles should gradually reflect this guide.

The emphasis of this manual is more on explaining what to do, and less on how to do it. For instructions explaining how to markup your contributions, see the markup guide.

Mechanics

Use good spelling and grammar

• Spelling and grammar, partly due to the spellchecking defaults and partly due to prevalence, is standardized in the American form. Regarding the spelling of links, redirects may be necessary.
• Spell words correctly. This site includes a spellchecker. Various editors and word processors contain or utilize spellcheckers. Various utilities such as aspell or ispell are available. However, do not let concerns regarding spelling errors prevent you from contributing.
• Use good grammar. Use a grammar-checking program or take other steps to ensure correctness. Again, do not let concerns regarding correctness prevent you from contributing.

Article introduction

• Generally, the first paragraph should contain a few sentences introducing the topic in a general sense prior to expanding on the topic in more detail. For example:

A game is an object generally used to have fun. Currently, games are one of the most popular forms of entertainment, and have been around for thousands of years.

However, let your content dictate your presentation.

• The first instance of the title of the page should be bold. Note the bold "manual of style" at the beginning of this page.

Headers

• Capitalize the first word and any proper nouns, but leave the rest of the words in lower case.
• Don't create links in headers - they're not easy to see relative to links that appear in ordinary body text.

Links

• Before creating a new link, first search for it and likely variants. This avoids redundant material, redundant links, or conflicts.
• Link only relevant keywords. Not every possible linkable word needs to be linked; rather, link to only those articles that the reader would most likely want to follow for further pertinent information.
• However, try to make sure there is at least one link in each article so that the reader never arrives at a 'dead-end' page.
• Articles and links should be on Linux or general computer topics relevant to Linux, though brief digressions on specifically non-Linux topics may be appropriate.
• Make links in the singular form. Consistency promotes ease of editing. If it is necessary to use the plural form, plural [[link]]s can easily be made and will render as a single highlighted word.
• As of this writing, links are case sensitive. Title/link applications and entities according to their official names (MPlayer, IBM) and, otherwise, the case should be as if it were The Title of a Book. If necessary, in the circumstance of a wrongly or confusingly cased title, supply a redirect.
• When creating links which consist of 2 or more words, don't capitalize second and subsequent words, unless the words are either proper nouns, or are commonly used in their capitalized form in that context.

External and 'See also' links

• External links should be formatted as "footnotes" when in the body of the text. This is done by enclosing the URL with single brackets i.e. [http://www.kde.org] --> [1]. Additional external links for further reading should be placed at the end of the page in a section entitled "External links", using the heading (==External links==).
• If internal links do not fall within the body of the article, they should be listed in a section entitled "See also" which should come immediately before "External links" (if it exists) or at the end.
• These lists should be bulleted, using single asterisks.
• Short descriptive text should be supplied to replace long or ugly URLs and to simply be more informative. This is done with a pair of single brackets which encapsulates the URL, then a space, then the descriptive text (i.e. [http://www.kde.org KDE] comes out as KDE). Additional descriptive text, if truly necessary, can be added to the right of the link (outside the right bracket).

Markup

• Use as little HTML (i.e. <b>, <i>, etc.) as possible. A few cases where HTML may be necessary include block quotes, single line breaks, and underlining.
• Do not indent in order to separate paragraphs or create leading whitespace. It will misformat paragraphs as a single long line in fixed font. To separate paragraphs, simply leave a single blank line between each; to create leading whitespace, use the ':' markup.
• When first expanding acronyms, format it as usual except for bold initial letters. For example: GNU is a recursive acronym for GNU's Not UNIX.

Command syntax markup

• Prefix all commands meant to be performed by an ordinary user with '$' and all commands meant to be performed by the super-user/root with '#'.
• Format the names of commands in fixed font with <tt></tt>

Style

Be objective

• First, if in doubt, use facts, not opinions.
  • Good: "KDE is one of the most popular desktop managers for Linux." (a fact)
  • Okay: John Smith states that "KDE is an awesome desktop manager." (not as good)
  • Bad: KDE is the best desktop manager out, everyone should get it! (opinion)
• Second, use what specific people say, not a general group that you make up.
  • Okay: John Smith states that "KDE is an awesome desktop manager." (not as good)
  • Bad: Critics say that KDE is a horrible desktop manager. (it's too general: who are critics, why do they say this, do they really say this, etc.)
  • Bad: Lots of people think that KDE sucks (how can we tell this is right or wrong? define lots of people)
• People on kde.org are probably going to say that KDE is better than GNOME, and vice versa. Therefore, if you are writing an article about desktop managers, you should attempt to get all points of view (those who like KDE, those who like GNOME, etc.).

Material from external sources

• Do not copy and paste material from sources, as most sources are generally copyright (and the use of copy and paste is not recommended, anyway). Also, do not copy from the Wikipedia, as the GFDL and the CC licenses (the latter being the license of this site) are incompatible.
• Incorporate license-compatible material where necessary and appropriate. Edit such material to make it correct and up to date rather than blindly copying and pasting.
• You should always cite your sources. Make a little section at the bottom (something like ==Sources==) and put sources at the bottom (using bullets, i.e. *source).