Difference between revisions of "Tutorials Style Guide"

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:

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

@@ Line 1: / Line 1: @@
+__NOTOC__
 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 [[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].
-==Title of tutorial "chunk"==
+===Formatting conventions===
-[[Image:Mac calawah1.png|thumb|250px|right|Figure 1]]
+====Use an Ordered List to Identify Steps====
-[[Image:Mac calawah2.png|thumb|250px|right|Figure 2]]
+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 />
-[[Image:Mac-calawah3.png|thumb|250px|right|Figure 3]]
+'''Example:'''
+# Go to the dashboard and click '''Appearance'''
+# Choose your template by clicking '''Activate'''
-Brief overview to orient what is being done in this section. May not always be necessary.
+====Navigational Sequence====
+When indicating navigation in the application use bold text and the '''>''' to indicate navigational sequence <br />
+'''Example:'''
+# Click '''Go > Connect to Server '''
-===Subheading===
+====Variable text====
-Brief overview to orient what is being done in this section. May not always be necessary.
+Use italics for text that should be replaced by user specific information <br />
-# Numbered step
+'''Example:'''
-# Numbered step with link to larger version of figure graphic. [[:Image:Mac calawah1.png | Figure 1]]
+# Enter your ''username''
-# Numbered step
-# Numbered step with link to larger version of figure graphic.. [[:Image:Mac calawah2.png | Figure 2]]
-# Numbered step with link to larger version of figure graphic. [[:Image:Mac-calawah3.png | Figure 3]]
-# Embedded images work well when small[[Image:Mac network icon.png]]
-===Subheading===
+====Punctuation and Capitalization====
-Brief overview to orient what is being done in this section. May not always be necessary.
+*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]]
-# Numbered step. Use bold text when indicating menus for clicking, i.e. '''Go > Connect to Server'''.
-# Urls should be written out fully'''https://studentfiles.evergreen.edu'''
-# Embedded small images [[Image:Mac network icon.png]] can be useful.
+===Page layout===
+* See [[Tutorials Style Guide - Example Page Layout]]
+* Usage of section headers must be consistent
-===See also===
-*[[Connect to Hurricane - Mac OS X]]
@@ Line 34: / Line 47: @@
- [[category:Workshops and Tutorials]]
+[[category: Wiki Admin]]