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. You can insert your personality in the classroom.
+
* 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 10: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

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