Proposal

Starting in 0.6, we are proposing a process by which we use more formal specs in a printable html document format, checked into cvs is instead of creating them directly on the wiki.

Motivation

There are several motivations for considering more formal written specs.

1. There seems to be a need for a higher level of technical documentation, anywhere from architecture specs, technical design as well as detailed UI and use case scenarios. It will be beneficial if this type of information were available in a specific location as well as in a consistent format.

2. We have a variety of different consumers for the specs that will want to have insight into the planning and design as well as the implementation details. This includes people such, developers, dev managers, QA, Design, the community etc.

3. We would like to try and combine engineering details as well and UI and functional details into a single document. These could become quite lengthy and managing them in wiki pages becomes more problematic. A separate document format that is printable would be more appropriate.

4. To date, most of the official specs are owned and authored by the design team. Going forward, this will not necessarily be the case. We will have documents owned and authored by design but have different contributors including developers. There will also be some specs owned by development but contributed to by design. Due to the expanded list of people who will be editing these documents, we are proposing a more managed process by which we can store them in CVS.

Comments on Process

Although we are moving to a more consistent format, it does not mean that the specs development process will not be iterative and collaborative in nature. Some specs will center around a more formal technical proposal that is defined very early on in the lifetime of the document. Other specs included those that are very UI centric may only start out as a list of use cases and be development collaboratively between engineers and the design team. The key is by having a more consistent format, people know what to expect and it's easier to get a sense of where we are in the process. By remaining flexible on the process we can accomodate the varying needs across different groups in the organization.