DocTeam/StyleGuide

Not logged in - Log In / Register

Revision 6 as of 2008-02-11 16:04:46

Clear message

ContentsBRTableOfContents

Intro

Welcome to the Launchpad Help style guide.

If you would like to contribute to Launchpad's help materials, please follow these guidelines.

Our approach to writing help

When you're writing Launchpad help, remember that you're probably writing for someone quite like yourself.

If you read only one part of this guide, read the following:

American English

We use American English on the Launchpad help wiki. This is to make our help materials consistent with other Canonical projects, as well as help materials for other software and services.

Some material is in British English but will be either converted or superseded.

Application names

Application names are capitalized and should not be prefixed by "Launchpad", unless it would otherwise be confusing.

At present, we frequently use the following application names:

Titles and headlines

Titles and headlines are written in sentence case and without a closing period. For example:

Right: How to file a bug in Launchpad

Wrong: How to File a Bug in Launchpad.

Lists

Lists are a useful way to improve the readability of two or more related items.

In most cases, an unordered (bullet) list is appropriate. You should only use an ordered (numbered) list if the order of the items is significant: e.g. for the steps of a process or chronologically ordered items.

List punctuation and capitalization

We use two types of list in Launchpad help materials:

If the list is part of an existing sentence, its capitalization and punctuation should reflect that. Use a colon where the sentence splits into the list and a period at the end of the final bullet. For example:

There are four items on my desk:

 * my laptop
 * an empty mug
 * a photo of my son
 * my wireless router.

If I need to go into further detail, it might be more appropriate for each item to be a sentence of its own. For example:

My first four computers were:

 1. Sinclair ZX81: 1K of RAM, no sound, membrane keyboard and monochrome graphics.
 2. Sinclair ZX Spectrum 48+: eight colour graphics, single channel sound and a proper keyboard.
 3. Sinclair ZX Spectrum 2+A: built-in cassette deck, three channel sound and some incompatibilities.
 4. Amiga 500+: 4096 colour graphics, custom chips and pre-emptive multi-tasking.

In effect, the first item in the list is a continuation of the previous sentence. As these items are in chronological order, I've used a numbered list.

Semi-colons

Don't use semi-colons at the end of each item as they are an unnecessary visual distraction.

Screen shots

attachment:proj-announce.png

Project announcements in Liferea

Screen shots help put your instructional text in context and to reassure your reader that they're following correctly. Use them wherever they will clarify what you're writing.

To make screen shots as effective as possible, we have some rules:

MoinMoin markup for a screen shot table

||<tablestyle="float:right; font-size: 0.8em; width:30%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;">attachment:screen-shot-file-name.png||
||<style="text-align: center;">'''Short annotation'''||

Templates

[:DocTeam/StyleGuide/UserGuideTemplate]