Ingenuity: User Documentation, Style and Ingenious Algorithm(s)

Ingenuity: User Documentation, Style and Ingenious Algorithm(s)

1.1.8 Importance of user documentation

IB Subtopics

Documentation

User documentation can be provided in a variety of forms, both online and offline. It should include instructions that are mandatory for the system to operate and should contain frequently asked questions, which are always necessary for new users. (you don’t have to include the following for your IA’s client)

Possible types of documentation for users include:

  • Manuals, printed or online.
  • Email Support
  • Embedded Assistance or Integrated User Assistance. This includes embedded help systems or tutorials.
  • Frequently Asked Questions, online or printed.
  • Live Chat Sessions with a customer support representative.
  • Online Portals of Web Portals, which include any of the above.

Possible types of documentation for developers include:

  • Javadocs or Sphynx
  • Inline Comments (include in IA code)
  • Documents, like a README, that outlines the purpose or the program. It can also include how to run the program and any dependencies/libraries needed. (include in IA code)

Style

We’ve use a style guide for Java in this course, but you might be using a different language for your project. You and your team must decide on a style and make sure to stick to it. The style, above all, needs to be consistent.

However, across any language you must remember the following:

• Structure and layout of your code is logical and easy to follow
• Comments in-line code (ideally following the conventions for your programming language)
• Names are meaningful and follow a consistent scheme (variables, methods, classes)
• Use of Input validation techniques
• Data is well structured (eg: use arrays/objects to avoid names like player1, player2, players)
• The use of global variables is minimized or avoided altogether. Where used they have been well justified.
• Use of error checking to “fail gracefully” (file exceptions, network exceptions, user input exceptions, etc)
• Make sure to let the user know when something went wrong
• Use of presentation and logic code separation where practical (model-view-controller or similar)
• Use of an elegant abstraction of classes, properties and/or methods.
• Use of algorithmic thinking that is elegant &/or efficient in their operations.
• Use encapsulation to avoid dependence on or creation of side-effects
• Functions are sufficiently modular so each achieves one task