Difference between revisions of "Assignment 5"

From CompSciWiki
Jump to: navigation, search
(fixed breadcrumbs)
m (grammar fixes)
 
(5 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
Below you will find real examples of what previous students have submitted, complete with comments from the marker.  Learn from their successes and avoid their follies.<br>
 
Below you will find real examples of what previous students have submitted, complete with comments from the marker.  Learn from their successes and avoid their follies.<br>
 
<br>
 
<br>
−
[http://www.google.ca Example Assignment 1] <br>
+
[http://courses.cs.umanitoba.ca/Documents/70277/Using%20nTreePoint%20Forms%20for%20Assignment%20Submission%20and%20Grading.pdf Example Help Documentation] <br>
−
The first example is an excellent illustration of the payoff of good planning and the consequences of neglecting thorough [[Editing_and_Revising| editing]].<br>
+
This example assignment is a very well written help document for the nTreePoint system.  It was written by previous students and is currently in use by the staff. This document is written as a step-by-step tutorial. It follows all the key guidelines of good instructions and instructional documentation.  The fact that it is still in use today underscores the positive effect of sticking to those guidelines.<br>
−
<br>
+
 
−
[http://www.google.ca Example Assignment 2] <br>
+
−
The second example is an excellent illustration of the payoff of good planning and the consequences of neglecting thorough [[Editing_and_Revising| editing]].<br>
+
  
  
 
|Introduction =  
 
|Introduction =  
−
Introduction here.
+
This assignment deals with every computer science student's favorite subject: help documentation. Love it or hate it, help documentation is an important part of any development project.  Regardless of how powerful or well coded your software is, the end user will require help documentation to take full advantage of it.  This assignment will hone your help documentation writing skills so you can avoid late night support calls in the future.
 +
 
 +
There are 4 major factors that contribute to a good help document:
 +
# [[Purpose| Determining what questions the users will need answered.]]<br>
 +
# [[Audience| Determining who will be reading the help documentation.]]<br>
 +
# [[Graphics| Ensuring the document can be easily related to the actual software.]]<br>
 +
# [[Page_Layout| Ensuring the document can be easily read, or used as a reference.]]<br>
 
}}
 
}}
  
Line 21: Line 25:
  
 
===Purpose===
 
===Purpose===
−
<br>
+
*The purpose of each section should be clearly stated.<br>
 +
*State the purpose before a list of steps. ('Why' before 'How')<br>
  
 
===Audience===
 
===Audience===
−
<br>
+
*Ensure language is appropriate to all readers.<br>
 +
*Present definitions in a form that can easily be skipped by more advanced readers.<br>
  
 
===Style===
 
===Style===
 +
*Use whitespace to separate sections of text.<br>
 +
*Instructions should use numbers, not bullets.<br>
 +
*Apply the ABC approach throughout.<br>
 +
*Images should be directly referenced by the text.<br>
 +
<br>
  
−
 
+
==Key Applied Topics==
−
==Applied Topics==
+
# [[ABC Approach]]<br>
 +
# [[Audience]]<br>
 +
# [[Instructions]]<br>
 +
# [[Page Layout]]<br>
 +
# [[Graphics]]<br>
 +
# [[Instructional Documentation]]<br>
 +
# [[Using Google Docs]]<br>

Latest revision as of 02:43, 20 April 2008

COMP3040 > Assignments > Assignment 5: Group Help Documentation


Introduction

This assignment deals with every computer science student's favorite subject: help documentation. Love it or hate it, help documentation is an important part of any development project. Regardless of how powerful or well coded your software is, the end user will require help documentation to take full advantage of it. This assignment will hone your help documentation writing skills so you can avoid late night support calls in the future.

There are 4 major factors that contribute to a good help document:

  1. Determining what questions the users will need answered.
  2. Determining who will be reading the help documentation.
  3. Ensuring the document can be easily related to the actual software.
  4. Ensuring the document can be easily read, or used as a reference.

...by students

Below you will find real examples of what previous students have submitted, complete with comments from the marker. Learn from their successes and avoid their follies.

Example Help Documentation
This example assignment is a very well written help document for the nTreePoint system. It was written by previous students and is currently in use by the staff. This document is written as a step-by-step tutorial. It follows all the key guidelines of good instructions and instructional documentation. The fact that it is still in use today underscores the positive effect of sticking to those guidelines.


Avoid Common Pitfalls

Those who cannot learn from history are doomed to repeat it. Many students have tackled this assignment before you. Don't make the same mistakes they did.

Purpose

  • The purpose of each section should be clearly stated.
  • State the purpose before a list of steps. ('Why' before 'How')

Audience

  • Ensure language is appropriate to all readers.
  • Present definitions in a form that can easily be skipped by more advanced readers.

Style

  • Use whitespace to separate sections of text.
  • Instructions should use numbers, not bullets.
  • Apply the ABC approach throughout.
  • Images should be directly referenced by the text.


Key Applied Topics

  1. ABC Approach
  2. Audience
  3. Instructions
  4. Page Layout
  5. Graphics
  6. Instructional Documentation
  7. Using Google Docs
Retrieved from "https://hci.cs.umanitoba.ca/mediawiki/index.php?title=Assignment_5&oldid=6639"