Difference between revisions of "Tutorials Style Guide"

From Help Wiki
m
 
(17 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.
==Writing guidelines==
 
 
===Technical writing best practices===
 
===Technical writing best practices===
* Avoid chattiness or personal opinion. You can insert your personality in the classroom.
+
* Avoid chattiness or personal opinion. Insert your personality in the classroom.
* Use clear and concise language
+
* Keep it succinct. Use clear and concise language
* Hey you, don't 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?
 +
* 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====
 
Use italics for text that should be replaced by user specific information <br />
 
Use italics for text that should be replaced by user specific information <br />
'''Example:'''
+
'''Example:'''
# Enter your ''username''
+
# Enter your ''username''
----
+
 
  
 
====Punctuation and Capitalization====
 
====Punctuation and Capitalization====
 
*Start all numbered steps with a capital
 
*Start all numbered steps with a capital
 
*Do not punctuate the end of bulletted or numbered lists (no periods)<br />
 
*Do not punctuate the end of bulletted or numbered lists (no periods)<br />
'''Example:'''
+
'''Example:'''
#This is my first step
+
#This is my first step
#This is my second 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==
+
===Page layout===
* See [[Tutorials Style Guide - Example Structure]]
+
* See [[Tutorials Style Guide - Example Page Layout]]
 
* Usage of section headers must be consistent
 
* Usage of section headers must be consistent
  
Line 40: Line 48:
  
  
[[category:Workshops and Tutorials]]
+
 
 +
[[category: Wiki Admin]]

Latest revision as of 13: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:

  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
Example:

  1. Click Go > Connect to Server

Variable text

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

  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)

Example:

  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