Tutorials Style Guide

From Help Wiki
Revision as of 13:08, 12 July 2016 by Greenea (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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

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?
  • Be aware of best practices for creating link text.
  • Write effective page summaries.

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

  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

  1. Click Go > Connect to Server

Variable text

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

  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)


  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