Courseware Tutorial

Style Guide

General Rules

1. The ideal flow should be:
   1. Explain.
   2. Demo(s) with explanations.
   3. Exercise.
   4. Solution.
2. Keep in mind that the PDF of the courseware might be used for presentation.
   1. Use HTML lists (ul,ol) instead of comma-delimited lists.
   2. When you have multiple related headings followed by short descriptions consider using tables instead.
   3. Keep your descriptions as short as possible and use footnotes to make caveats or to point people to further reading on subjects not necessary for completing the labs. The trainer can fill in as appropriate.
3. Keep in mind that students will NOT be reading the manual cover to cover and will not be reading every paragraph during class.
   1. If you can make it shorter, do it.
   2. If it's not necessary, leave it out or put it in a footnote or in a reference table.
4. Ideally, no code will be shown that is beyond the scope of the class. If demo code does contain stuff that is beyond the scope of the clas:
   1. Be careful to point out that it is beyond the scope of the class.
   2. Ideally, provide a brief summary of what the code does (perhaps in a comment).

Specific Rules

Headings

1. Use appropriate decreasing levels of headings. For example, h1 subheadings should be h2s, h2 subheadings should be h3s and so on.

Lists

1. Use periods at the end of list items in lists in which one or more of the list items contains a phrase. When in doubt, use periods.
2. When leading into a list, end the previous sentence with a colon. For example, "The following browsers support CSS pseudo-classes:"

Demos vs. Code Blocks

1. In most cases, Demos are preferred to Code Blocks. Only use Code Blocks for:
   1. incomplete code.
   2. to draw further attention to something contained within a demo when explaining the demo.

<code>

1. Use <code> tag when mentioning syntax words, library classes/functions, etc.

<span class="FilePath">

1. Use <span class="FilePath"> for any file or directory names that come from the Demos/Exercises/Solutions.

Syntax and Code Blocks

1. For syntax blocks, always use the title attribute. For example:
   Syntax

   <div class="SyntaxBlock" title="Basic SELECT statement">...

2. For code blocks, the title attribute is optional.

Really Specific

1. Avoid the word "utilize". Use "use" instead. See http://ezinearticles.com/?Writing----How-To-Use-Use-Versus-Utilize-Correctly?&id=479574 for an explanation on this.

• PDF Version of Manual
• Associated files
• Video

If you are interested in writing courseware using this system, please email courseware@webucator.com.

All material in this Style Guide is copyright 2010 Webucator. The purpose of this website is to help you learn Courseware on your own and use of the website implies your agreement to our Courseware Creation System Terms of Service.