Difference between revisions of "Tutorial Guidelines"

From ESE205 Wiki
Jump to navigation Jump to search
 
(One intermediate revision by the same user not shown)
(No difference)

Latest revision as of 14:00, 29 August 2018

For completion of the class, each group will be required to publish at least one tutorial pertaining to a topic which they have expertise on based on the work completed for their project. In an effort to maintain clear, navigable, and uniform tutorials, groups must adhere to the following format

Tutorial Subsections

Overview

The overview section should be a brief, one to three sentence overview of what your tutorial may cover

Materials/Prerequisites

This section should contain a list of materials required to complete the tutorial, accounts necessary to complete the tutorial, or other prerequisites.

For instance, if your tutorial is about setting up a raspberry pi you should either require they have an SD card and walk them through flashing an OS onto the card, or list an SD card with installed OS in this section.

Process

This should be the meat of your tutorial, the actual steps to complete it. In general:

  • Avoid large paragraphs of text, tend towards clear, concise steps
  • Include pictures as much as possible, especially for key steps. This may be in the form of a photograph, screenshot, drawing, etc.
  • All text should be styled appropriately. Code should be in code blocks, key words and notes should be in bold.
  • Logical groups of steps should be broken down under different sub-headers within this section
  • Language should be grammatically correct, and the first person shouldn't be used

Authors

This section should contain a of list all group members here, as well as semester published

Group Link

This section should contain a link to the group project page, as well as the group's weekly log

External References

This section should contain any external references used in the writing of this tutorial (i.e. urls)

Other Guidelines

  • Tutorials should follow a naming convention which categorized them under a logical alphabetical letter. For instance:
    • Bad tutorial name: Using a servo with a raspberry pi 3. This would put this tutorial in U for Using, which has nothing to do with the actual content of the tutorial
    • Good tutorial name: Servo + Raspberry Pi 3. This both categorized the tutorial under a logical letter (S for Servo) but it is concise and to the point, reducing clutter
  • Each tutorial must be tagged under the categories under which it falls. These categories are the subcategories on the Tutorials page of the wiki
    • For Servo + Raspberry Pi 3, this would be tagged under both Electronics and Raspberry_Pi
  • All sections should always be included, even if they are empty (just list N/A)