Difference between revisions of "Tutorials Style Guide"
From Help Wiki
(→Formatting conventions) |
m |
||
| (27 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| + | __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. Insert your personality in the classroom. |
| − | * Use clear and concise language | + | * 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? | + | * 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 [[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==== | |
| − | Example: | + | 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==== |
| − | + | When indicating navigation in the application use bold text and the '''>''' to indicate navigational sequence <br /> | |
| + | '''Example:''' | ||
| + | # Click '''Go > Connect to Server ''' | ||
| + | ====Variable text==== | ||
| + | Use italics for text that should be replaced by user specific information <br /> | ||
| + | '''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)<br /> | ||
| + | '''Example:''' | ||
| + | #This is my first step | ||
| + | #This is my second step | ||
| + | #This is my third step but I need two sentences. See [[:Image:Mac calawah1.png | Figure 1]] | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| + | ===Page layout=== | ||
| + | * See [[Tutorials Style Guide - Example Page Layout]] | ||
| + | * Usage of section headers must be consistent | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| Line 55: | Line 49: | ||
| − | + | [[category: Wiki Admin]] | |
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
