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:
Keep it simple: minimize sub-clauses in sentences. Aim for one idea or action per sentence. Start a new paragraph when dealing with a new concept. Use shorter words, where possible.
Write in small chunks: write about concepts one at a time and in the order your reader needs to know about them. Split applications into features/processes. Split processes into steps.
Show don't just tell: use examples to demonstrate what you're describing. Use cropped screen-shots liberally.
Reward your reader: give them frequent opportunities to achieve something.
Establish a relationship with your reader: write in the second person (i.e. "upload your branch", not "the user should upload their branch"). Be friendly.
Don't state the obvious.
Offer supplemental information: link to further reading wherever possible.
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:
- Translations
- Bug Tracker
- Code Hosting
- Blueprint
- Answers
- Soyuz
- Personal Package Archives.
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:
- continuations of an existing sentence
- those with items that each form a sentence of their own.
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
|
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:
Crop: retain only enough of the screen shot to illustrate your text and place it in the context of the page. Never show browser window borders.
Highlight: use a two pixel, hard, red (#f00) rectangle to highlight only one or two important elements of the screen shot.
Retain original size: where possible, do not shrink or zoom your screen shots.
Use PNGs: save your screen shots as PNG files, selecting the appropriate palette size to give the best file size without compromising the quality of the image.
Place in context: we use a table that allows us to annotate screen shots with a short description and also brings visual consistency to screen shots. If the screen shot is directly in the flow of your text and obviously linked to the text to which it refers, use your judgement as to whether it needs a border and description.
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'''||