I'm trying to make and demonstrate a more methodological development model here. The documents are a simplified version of a system that I had used at a previous employer. A lot of their documentation needs are unnecessary in this framework. For example, there is no need to satisfy stockholders and a board, there is no need for a formal sign-off procedure.
Also somethings that required a lot of bookkeeping in a formal office document environment, such as maintaining verification and validation links up the chain from design back down to requirements can be handled more simply in this case with hyperlinks.
The initial documents are:
- Product Description: a relatively brief discussion of what the idea is.
- Requirements: again terse and simple, this shouldn't be taking a major part of the development effort. What need to be done functionally and technically. Items here carry all the way up to implementation. Anything in design or implementation should be able to trace back here. Every thing here should be covered.
- High Level Design: This is more complex. This describes approaches of how to meet he requirements.
Some document types I'm not tackling right now are:
- Marketing doc: this gives a very high level view of the project. It covers 'Why', 'User Experience', 'Data' and 'Feature Function' from the 10,000 foot level. Good things but maybe this is the function of the project home page
- Project Charter: the internal 10,000 foot view and the necessary sign-offs to get the ball rolling. I'm not sure how much of this may be appropriate, and whether most of what is can't be put into a requirements doc.
- Breaking Requirements into Functional and Technical: More detailed than we need, I think.
- Component Design: not there yet. Module documentation strings?
I'm trying to expose this methodology for a couple of reasons. First, in many activities I see no documentation of what they are supposed to to. It is difficult if not impossible to ascertain what they are expected to do or not expected to do at any given time. For example, in an early version of the Calculate activity I only discovered the fact that it is a graphing calculator because there was a screen shot of it plotting an expression. Second, I suspect that a good number of developers for Sugar and the XO will be amateurs or hobbyists. However, their potential market numbers in the millions, so some lessons in formalism is not out of place.
For developers out there with their own methodologies, great. This is aimed more at those who don't.
This system was evolved over a period of years as an in-house methodology, and is synthesized from a number of sources. I'll try to add references.