Documentation Overhaul DoW
Status
This project just started. We plan to start the first iteration around June 15 2011. We plan 8 weeks per iteration.
Representatives of Stakeholders
We need volunteers willing to represent the stakeholders. So far we have:
- Cliff Jones - representing the contracting body (Deploy)
- Rainer Gmehlich - representing an industrial partner (Bosch)
- Andreas Roth - representing an industrial partner (SAP)
We would really like to have at least two volunteers from the industrial partners, two academic partners and one representative from Systerel. More volunteers are welcome.
The task of the reviewers is to provide feedback in a timely manner.
First Iteration
WP1-1: Styles Guides and Templates (16mh)
Once we decide on the form for the documentation, we will create a style guide to ensure consistency. We will also provide templates as needed, to simplify the creation of the documentation.
Deliverable: A Guideline for content creators and templates to go with it.
WP1-2: Wiki Migration or Version Plan (4mh)
Content must be accessible at all times. However, we will either migrate or restructure data significantly. We need a plan describing the approach.
Deliverable: A Guideline for content migration
WP1-3: Reference Section (20mh)
The Reference Section will be the most comprehensive part of the documentation. It will consist of a number of chapters. At this point we see at least the following sections:
- Event-B Reference
- Mathematical Notation Reference
- Modeling Language Reference
- Proof Tactics
- GUI Elements
- Glossary
There may be more. We must have a good understanding of the content we intend to cover. Otherwise we won't be able to allocate our resources wisely.
The FAQ will grow naturally and won't need a detailed plan beforehand.
Deliverable: The table of contents of the reference section (1st and maybe 2nd level)
WP1-4: Tutorial outline (20mh)
The tutorial is most likely the first thing new users are being confronted with. Thus, we feel that this chapter requires a lot of diligence. Also, we will perform user tests with the tutorial, once created. The tutorial will guide the user through installation, ensure that the mathematical background exists, introduce the GUI and guide the user through a few modeling sessions.
We feel that the current tutorial overwhelms the user by focusing on too many aspects at the same time. For instance, we believe that the first model must allow all proofs to be discharged automatically. Deliverable: The table of contents of the tutorial, including the description of the individual sections.
WP1-5: First iteration on Tutorial (80mh)
Our goal is to use the remaining time of the first iteration to make the tutorial rudimentary complete. This means that all examples are worked out and that most of the copy stands. There may be gaps, but only if the gaps don't impair the usefulness of the tutorial (e.g. the section on the mathematical notation may refer to the Abrial-Slides).
We expect that during this work, the rest of the documentation will start to fill up with placeholders (e.g. empty entries in the reference section.
Deliverable: The roughly completed Tutorial.
WP1-6: Iteration Review (20mh)
In addition to discussion the results so far, we will decide on the details of WP2-1.
Second Iteration
WP2-1: Migration and Creation of entries in the Reference Section (80mh)
We will start filling the reference section. We expect a number of sections to be quite labor-intensive, especially if it involves creating many screenshots.
Deliverable: Completed Parts of the Reference Section.
WP2-2: User Tests of Tutorial (60mh)
We will design metrics to evaluate the effectiveness of the tutorial. We will recruit students and ask them to work through the tutorial. We will attempt to recruit some of the Deploy industrial partners as well.
Deliverable: Results of the user tests
WP2-3: Iteration Review (20mh)
The results will be evaluated, particularly on whether the tutorial needs more focus or not.
Third Iteration
WP3-1: Completion of the Reference Section (100h)
The goal is to fill in all blanks in the reference section at this point. We may keep a list of entries that need improvements.
Deliverable: Complete Reference Section.
WP3-2: Completion of the Tutorial (20mh)
We will incorporate the feedback from the review, which is hopefully not much.
Deliverable: Complete Tutorial.
WP3-3: Provide context to give the documentation a whole appearance (20mh)
At this point, we will pay attention to the document “as a whole”. We will make sure all sections have proper introductions, check the style, etc. We will also create a list of sections that need particular attention.
Deliverable: Improved documentation, List of trouble spots.
WP3-4: Iteration Review (20mh)
The last iteration will be used for “polishing” In this review, we allocate the resources as needed.
Forth Iteration
WP4-1: Polishing (130h)
Polishing, as decided at the last review.
Deliverable: Complete Documentation.
WP4-2: Final Review (30mh)
In addition to reviewing the last iteration, we will record feedback on the project as a whole.
