Overview and tutorial maintenance

Please follow these rules when creating or modifying overview or tutorial pages.
  1. Use simple file formats
    These pages are not polished works of art but living documents that have to stay in step with our code or they are worse than useless. Indeed they should be treated as part of the code. This means that at least anyone in the core group should be able to correct any mistakes they find and to make this as easy as possible we should limit documents to a few simple types for example:- See overview.template that can be used as a template for new overviews and tutorials.

  2. Each page is organised into 3 sections

    1. One or a few self-contained "slides"
      The idea is that a user clicks on an overview or tutorial and sees a simple self-contained summary that fits in one or a few single pages (Aside: most overviews still have .gif file slide which was Nick's dumb idea, but see overview.template and slide_maker.pm to see how a reasonable alternative can be made that is much easier to maintain).

      These "slides" should be:-

      • Self contained. A new postgraduate starting on MINOS should have sufficient background knowledge to comprehend them in isolation.
      • Links are encouraged, but only to other "slides" on other overviews and tutorials.
      After the "slides" come the detailed material which can be broken into sub-documents and have links to other parts of WebDocs and beyond.

      The purpose of this rule is twofold:-

      1. Orientation. A big problem for newcomers is information overload. So long as they just navigate within slides they should not get indigestion. Also, in the early days they can return to any slide to remind themselves of some key concept.

      2. Navigation. Having got some level of orientation the next thing a user wants is to be able to locate more detailed information within WebDoc. These topic-based pages can have links into the rest of WebDoc as an alternative to the main index as a way of navigating.

      For the tutorials orientation and navigation are not the principle aims. They are end documents in their own right but can still serve these purposes. Indeed it is important that they contain links to WebDocs were additional information can be found.

    2. Notes and Further References
      In this section the contents of the slide can be developed. Beyond introducing concepts for the novice, don't reproduce material available in WebDocs and beyond, instead provide links to them so that the section provides a topic based index.

    3. Exercises
      Use this section for exercises and tutorials.

    4. Add running examples to validation list
      validation procedures should contain a list of all the running examples to simplify validation.

    Go Back to the The OO Companion Top Page

    If you have any comments about this page please send them to Nick West