Difference between revisions of "Tutorials Style Guide"
From Help Wiki
m |
(Try not to use "you") |
||
| Line 3: | Line 3: | ||
==Writing guidelines== | ==Writing guidelines== | ||
===Technical writing best practices=== | ===Technical writing best practices=== | ||
| − | * Avoid chattiness or personal opinion. | + | * Avoid chattiness or personal opinion. Insert your personality in the classroom. |
* Keep it succinct. Use clear and concise language | * Keep it succinct. Use clear and concise language | ||
* Try not to use "you" | * Try not to use "you" | ||
* Start each step with a verb if possible. What is the person '''doing''' specifically? | * Start each step with a verb if possible. What is the person '''doing''' specifically? | ||
| − | * Is it easy to scan for important content? | + | * Is it easy to scan for important content? |
| − | + | ||
===Formatting conventions=== | ===Formatting conventions=== | ||
Revision as of 09:11, 20 October 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
When indicating navigation in the application use bold text and the > to indicate navigational sequence
Example:
- Click Go > Connect to Server
Variable text
Use italics for text that should be replaced by user specific information
Example:
- 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:
- This is my first step
- This is my second step
- 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
