Difference between revisions of "Tutorial Guidelines"
| Line 1: | Line 1: | ||
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. | 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''' | In an effort to maintain '''clear, navigable, and uniform tutorials, groups must adhere to the following format''' | ||
| + | == Tutorial Subsections == | ||
=== Overview === | === Overview === | ||
The overview section should be a brief, one to three sentence overview of what your tutorial may cover | The overview section should be a brief, one to three sentence overview of what your tutorial may cover | ||
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
Contents
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)
