Difference between revisions of "Tutorials Style Guide"

Revision as of 09:07, 1 November 2011

This style guide is intended for use in the development of workshop/application tutorials in the computing wiki.

Writing guidelines

Technical writing best practices

• Avoid chattiness or personal opinion. Insert your personality in the classroom.
• Keep it succinct. Use clear and concise language
• Try not to use "you"
• Start each step with a verb if possible. What is the person doing specifically?
• Is it easy to scan for important content?

Formatting conventions

Use an Ordered List to Identify Steps

Anytime you are a describing a sequence of 2 or more steps, use a numbered or ordered list. You can combine finding a location and taking action in a single step i.e.,

1. Go to the dashboard and click Appearance
2. Choose your template by clicking Activate

Navigational Sequence

When indicating navigation in the application use bold text and the > to indicate navigational sequence
Example:

1. Click Go > Connect to Server

Variable text

Use italics for text that should be replaced by user specific information
Example:

1. Enter your username

Punctuation and Capitalization

• Start all numbered steps with a capital
• Do not punctuate the end of bulletted or numbered lists (no periods)
  

Example:

1. This is my first step
2. This is my second step
3. This is my third step but I need two sentences. See Figure 1

Page layout

• See Tutorials Style Guide - Example Page Layout
• Usage of section headers must be consistent