Scratch Project: Documentation

For a program to be useful, it needs to have three qualities:

  • Correctness—In other words, the program should do what it’s supposed to do. Smaller components of a program must themselves be correct to form an overall correct program. Imagine a calculator program that produced output indicating that 2 + 2 = 3. The usefulness of this calculator would certainly be suspect. We may consider looking at how the addition procedure is executing. The style of the program can also affect the determination of program correctness.
  • Efficiency—Now imagine that the calculator were fixed so that it always produced correct output, but took a very long time to do it. Entering 2 + 2 = now returns the proper answer 4, but only after spending 12 minutes processing its input. The usefulness of this calculator would certainly be suspect.
  • Clarity—Imagine that the calculator has been altered to be both correct and efficient. What other quality could possibly make it unusable? Imagine a calculator in which to add a 2 and 2, some other key sequence than 2 + 2 must be entered. By not knowing the proper key sequence, or more generally how the calculator functions, you would certainly have doubts about the usefulness of this calculator. Note: The calculator linked above is actually very useful, once you’ve mastered the input mode. Try the examples linked at the top of the page. How does it work?

In this assignment, you will concentrate on the third point—clarity. Write up a document detailing how your application is used. You should concentrate on the following (as applicable):

  • What does your application do? What problem does it solve?
  • How is it used? What are the specifications for input? What constitutes valid input? Invalid input?
  • What are some common examples of its usage?
  • What are any limitations of which users need to be aware?
  • How might the program differ from user intuition? How is it unlike other, similar applications?