Diff for "DocTeam/StyleGuide"

Not logged in - Log In / Register

Differences between revisions 3 and 4
Revision 3 as of 2008-02-07 15:44:31
Size: 5577
Editor: vc7-1-240a
Comment: lock to prevent vandalism and keep authoritative
Revision 4 as of 2008-02-07 22:21:19
Size: 5527
Editor: 77-100-239-119
Comment:
Deletions are marked like this. Additions are marked like this.
Line 6: Line 6:
Welcome to the Launchpad Help style guide. Consistency is important in communicating clearly. Welcome to the Launchpad Help style guide.

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:

  • 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

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 all screen shots: 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 important parts: 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.

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'''||

Example screen shot

attachment:proj-announce.png

Project announcements in Liferea

DocTeam/StyleGuide (last edited 2008-06-17 14:21:18 by localhost)