Tutorials Style Guide
From Help Wiki
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.
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
- Go to the dashboard and click Appearance
- Choose your template by clicking Activate
When indicating navigation in the application use bold text and the > to indicate navigational sequence
- Click Go > Connect to Server
Use italics for text that should be replaced by user specific information
- 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)
- This is my first step
- This is my second step
- This is my third step but I need two sentences. See Figure 1
- See Tutorials Style Guide - Example Page Layout
- Usage of section headers must be consistent