Difference between revisions of "Tutorials Style Guide"
From Help Wiki
m |
m |
||
| (9 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
__NOTOC__ | __NOTOC__ | ||
This style guide is intended for use in the development of workshop/application tutorials in the computing wiki. | This style guide is intended for use in the development of workshop/application tutorials in the computing wiki. | ||
| − | |||
===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? |
| − | + | * Be aware of [[Web Links Best Practices|best practices for creating link text]]. | |
| + | * Write [http://www.wyliecomm.com/2009/10/how-to-write-the-most-important-piece-of-copy-on-your-web-page/ effective page summaries]. | ||
===Formatting conventions=== | ===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 <br /> | ||
| + | '''Example:''' | ||
| + | # Go to the dashboard and click '''Appearance''' | ||
| + | # Choose your template by clicking '''Activate''' | ||
| + | |||
====Navigational Sequence==== | ====Navigational Sequence==== | ||
When indicating navigation in the application use bold text and the '''>''' to indicate navigational sequence <br /> | When indicating navigation in the application use bold text and the '''>''' to indicate navigational sequence <br /> | ||
'''Example:''' | '''Example:''' | ||
# Click '''Go > Connect to Server ''' | # Click '''Go > Connect to Server ''' | ||
| − | |||
====Variable text==== | ====Variable text==== | ||
| Line 21: | Line 26: | ||
'''Example:''' | '''Example:''' | ||
# Enter your ''username'' | # Enter your ''username'' | ||
| − | + | ||
====Punctuation and Capitalization==== | ====Punctuation and Capitalization==== | ||
| Line 32: | Line 37: | ||
| − | ==Page layout== | + | ===Page layout=== |
* See [[Tutorials Style Guide - Example Page Layout]] | * See [[Tutorials Style Guide - Example Page Layout]] | ||
* Usage of section headers must be consistent | * Usage of section headers must be consistent | ||
Latest revision as of 12:08, 12 July 2016
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
Example:
- 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
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
