Attendees

• Sheila, Chao, Katie, Lisa

Agenda

• Review requirements gathered so far from design and dev teams.
• Prioritize requirements and discuss.
• Review content items ( sections and artifacts that should be in the specs )...discuss and prioritize.
• Discuss collaborative and iterative process for developing specs. What do we do now? Do we want to make any changes?
• Specs as they apply to 0.5. What is the list of items we need to spec out, what should we do first, what level of detail.
• Success criteria. How are we going to determine if the changes we are making have impact.
• Next Steps

Requirements

• content, the docs have the right information
• location - people know where to find them in a consistent location
• current - they are up to date and capture agreements and decisions
• accessible - easy to open
• open office support
• there is a mechanism for comments/feedback loop
• concise - low overhead
• change controlled - cvs
• highly collaborative
• restricted updating - only by the set of people who should be updating them.
• printable
• table of contents
• very detailed
• structured, following a template
• a "document"
• not Word
• 2 documents, 1 for UI, 2nd for underlying details
• short but useful
• work flows that will be supported in the target release only - not bigger picture
• Wiki format is good
• capturing assumptions - what will NOT work
• if we cut a piece of functionality, remove it from the doc
• mechanism for spec review - counter proposal
• some level of task mapping within the doc
• running issues list
• the format can handle gifs etc.
• flexible for iterations, design doesn't build a full spec from day one then pass to engineering.
• content is filled out over time.
• low-overhead collaboration (input from others should be easily incorporation)

Content Sections

• Overview - why we are building this
• Summary - what our goals are for this release
• Glossary - defines terminology used in the doc
• Feature List
• End to End Use Case - give the overall picture of how the functionality is used.
• Detailed Use Cases - acceptance criteria.
• Deferred Features
• Stretch Goals
• Priorities/ Ordering of Implementation
• Development Tasks - Owners of areas of implementation
• Dependencies
  • IT considerations
  • Other projects/decisions
• Platform considerations
• Internationalization considerations
• Developer API

Discussion Summary

• discussed spec requirements and agreed that this was a fairly complete list.
• some of the primary points surfaced were the need for a flexible mechanism to support brief lightweight specs as well as something more substantial and structured. We want to accomodate both.
• we agreed that we need to have a mechanism for storing some docs in cvs and decided that html will be the easiest to work with.
• depending on engineering needs we will use a simple wiki spec or a doc in cvs. This will be determined by the engineering team ie: the sidebar features for 0.5 may be very simple but the collection sharing spec may be a much larger document.
• we also agreed we would experiment with 0.5 and meet at the end of the year to discuss what worked and what didn't.
• it was found that most of the content sections were required but these would be identified and discussed on a per spec basis.

Next Steps:

• we agreed that all specs would start with a central wiki "home page" which links to either a one-page wiki doc with the spec or a more lenghthy html doc stored in cvs.
• the home page can act as a central location for comments, revision history and links to schedule, design or engineering related pages.
• by supporting both the light-weight wiki page AND a more structured CVS doc we can accomodate some specs that will be lenghthier and more rigid in their construction ie: sharing collections.
• all specs will start out as a wiki page and iterate into something more structured.
• we will adopt a more "spec review" approach with engineers to discuss various phases of the spec writing process. The first iteration will be a simple wiki page review of a feature list. We can determine whether an html/cvs doc or a wiki spec is required and agree on artifacts (sections/content). The next iteration will be a review of the first draft with engineering. The iterations will continue throughout the design and development process. The wiki spac home page will be available for feedback, comments etc.
• all the content sections are flexible and the specs will be adapted to whatever is required. Although everyone indicated that they should be short, when prompted, people suggested a variety of sections that are necessary. Using all of these can result in a very lenghthy document. The artifacts will be agreed upon by engineering and design after the initial spec walk-through (one-page wiki doc).
• Sheila will be responsible for creating a 0.5 spec directory in CVS. This will be used by engineering as well as design to store developer specs, doc and any supporting docs.

-- SheilaMooney - 15 Sep 2004