Difference between revisions of "Tutorials Style Guide"

From Help Wiki
(Formatting conventions)
(Writing guidelines)
Line 9: Line 9:
  
 
===Formatting conventions===
 
===Formatting conventions===
* When indicating navigation in the application use bold text and the '''>''' to indicate navigational sequence
+
====Navigation Sequence====
 
+
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 '''
  
*Use italics for text that should be replaced by user specific information
+
====Variable text====
 
+
Use italics for text that should be replaced by user specific information <br />
 
+
 
'''Example:'''
 
'''Example:'''
 
# Enter your ''username''
 
# Enter your ''username''
Line 23: Line 21:
 
===Page layout===
 
===Page layout===
 
* Usage of section headers must be consistent
 
* Usage of section headers must be consistent
 
 
 
  
 
==Example structure for tutorials==
 
==Example structure for tutorials==

Revision as of 12:54, 24 October 2007

This style guide is intended for use in the development of workshop/application tutorials in the computing wiki.

Writing guidelines

Technical writing best practices

  • Remove the chattiness
  • Use clear and concise language
  • don't use "you"
  • Start each step with a verb if possible. What is the person doing specifically?


Formatting conventions

Navigation 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

Page layout

  • Usage of section headers must be consistent

Example structure for tutorials

Title of tutorial "chunk" (level 2)

Figure 1
Figure 2
Figure 3

Brief overview to orient what is being done in this section. May not always be necessary.


Subheading (level 3)

Brief overview to orient what is being done in this section. May not always be necessary.

  1. Numbered step
  2. Numbered step with link to larger version of figure graphic. Figure 1
  3. Numbered step
  4. Numbered step with link to larger version of figure graphic.. Figure 2
  5. Numbered step with link to larger version of figure graphic. Figure 3
  6. Embedded images work well when smallMac network icon.png


Subheading (level 3)

Brief overview to orient what is being done in this section. May not always be necessary.

  1. Numbered step. Use bold text when indicating menus for clicking, i.e. Go > Connect to Server.
  2. Urls should be written out fullyhttps://studentfiles.evergreen.edu


See also