Difference between revisions of "Style Guide"

From CS Support Wiki
Jump to: navigation, search
Line 7: Line 7:
 
=== Bulleted and numbered lists ===
 
=== Bulleted and numbered lists ===
 
We often need to provide step-by-step instructions or item lists in our documentation.  Use MediaWiki's [http://en.wikipedia.org/wiki/Help:List bullet (*) and numbered list (#) notations] to denote separate items.  If ordering of the list is critical (first do A, then do B), use a numbered list; otherwise, use bullets.
 
We often need to provide step-by-step instructions or item lists in our documentation.  Use MediaWiki's [http://en.wikipedia.org/wiki/Help:List bullet (*) and numbered list (#) notations] to denote separate items.  If ordering of the list is critical (first do A, then do B), use a numbered list; otherwise, use bullets.
 +
 +
=== Code blocks ===
 +
Use code blocks when providing command-line examples or text file snippets.  Prepend each line you want to appear in a text box with a space (this goes for blank lines too, if you want to embed a blank line within your code block).
 +
 +
=== Suspending MediaWiki markup ===
  
 
== General documentation guidelines ==
 
== General documentation guidelines ==

Revision as of 23:41, 16 February 2009

MediaWiki markup

First, please familiarize yourself with MediaWiki's markup. Wikipedia's cheatsheet and page editing articles are useful introductory references.

Using subsections to auto-generate tables of contents

Medium to large articles should be broken into subsections using MediaWiki's section heading notation. In addition to establishing a consistent convention for organizing pieces of articles, it also allows for automatic generation of tables of contents - see PBS for an example. If you use section heading dividers in an article, a hyperlinked table of contents will show up automatically, which makes navigation much easier for the reader.

Bulleted and numbered lists

We often need to provide step-by-step instructions or item lists in our documentation. Use MediaWiki's bullet (*) and numbered list (#) notations to denote separate items. If ordering of the list is critical (first do A, then do B), use a numbered list; otherwise, use bullets.

Code blocks

Use code blocks when providing command-line examples or text file snippets. Prepend each line you want to appear in a text box with a space (this goes for blank lines too, if you want to embed a blank line within your code block).

Suspending MediaWiki markup

General documentation guidelines

Article Size

Avoid creating articles that are so long that the reader has to scroll through several screens worth of content - break them into smaller articles. Use your best judgment, though, Goldilocks! If an article consumes a small fraction of a screen, consider whether it could be lumped into another related article.

Be Concise

Favor short, bullet-point explanations over lengthy paragraphs. Where a complex issue is covered, consider breaking topics out into "Quick Start" and sections for more detailed/advanced topics.

Spam prevention

Avoid writing out email addresses in text, as they can be harvested by spammers' web bots.

=