Filing Design Artifacts (as of Dec 2003)

@@@ -- This document needs to have a TOC and some intro text that outlines the structure of the document and explains that the actual proposal is down at the bottom.

---

Goals

Goal: Our design process is producing a lot of documents. We need to make sure that...

1. we know who the consumer is for each type of document
2. we're creating documents that are well suited (useful) to the person who needs the document
3. the documents are filed in a way that makes them easy to find
4. the documents are in sync with each other (consistent with each other)
5. the documents match the unified design/engineering process (milestone based deltas vs. waterfall specs)
6. we can tell, by looking at a document, what stage fo the process the doc is in
7. we document enough, but not too much

---

Types of documents

So far, we seem to have created about a dozen types of artifacts

type of artifact	example
images (wireframes, hand sketches, & screenshots)	newcontact.gif
undigested meeting notes	DesignIssuesMeeting20031103
usage patterns & user actions & use cases	DaveAllenUsagePatterns
feature lists	TasksFeatureList20031121
sets of questions and answers and open issues	SharingDesignIssues
automatically generated schema documentation	mail schema
XRC mock-ups
working notes	BuildingNavigation
glossaries	Projects.GlossaryOfKeyEndUserTerminology
schedules	ChandlerTimeline
deliverables for each dot release (or milestone) -- images, behaviors, content model mapping	ZeroPointThreeUI

---

People who need design info

• Engineers
  • screen shots with annotations -- Engineers need screen shots, probably with some text annotations explaining the affordances shown in the pictures.
  • milestone deltas -- Engineers need to know what features are being requested for the next milestone
  • sample data -- Engineers need sample data to test with
  • schema -- Engineers need schema to build on

• Mimi
  • detailed requirements -- Mimi needs to know all the requirements, at a fairly detailed level -- what users can do with Chandler (e.g. send mail)
  • schema -- Mimi needs to know what the schema looks like -- what attributes the UI will show
  • sample data -- Mimi needs to sample data that matches the schema. The sample data should be realistic (meaning, data that is representative of what differnt typical Chandler users would really have in their repositories).
  • user test results -- ...feedback from non-OSAF users...

• Product managers
  • estimates -- Chao & Brian need estimates from engineers, in order to be able to put together a rough schedule and track slippage

• Management
  • schedule and slippage -- Management needs to know how long it will take and how much it will cost.

• Design team
  • past decisions and open issues -- The design team needs to know what decisions we've already made (so as not to revisit them) and what open issues are left (in order to close them).

• Everyone
  • We all need to be on the same page about what we're doing and what we're not doing. If possible, it would be good to be literally on the same page -- each fact should appear in only one place -- avoid duplication and pages that are out of sync.

---

Different views into the data

Different people seem to need different views into the same information.

• Some people want summary views; some people want detailed lists.
• Some people want to see a complete spec
• some people want to see just a delta for the current dot release -- this can be high level summary
• Some people want to see just the items that need UI affordances; some people want to see all the features.

Feature Table Columnns

Here's a list of the different columns and groupings that different people have asked for, or that different people have used on the different feature list pages.

Columns of a feature table (attributes of a spec item):

• item name -- "requirement", "feature", "spec item", "open issue"
• description
• link to image
• link to bugzilla task
• anchor tag so things can link to this
• status -- "design challenge", "design issue", "to be resolved by user testing"
• ordering -- done, 1, 2, 3, 4, 5...
• release -- 0.3, 0.4, 0.5

...other meta info people want to sort by, group by, or filter by

• by owner -- who's implementing it
• by UI prominance -- UI vs. not-UI -- Mimi's "level of use" metric
• by summary vs. detail -- example: summary vs. detail
• by capplet (or project)
• by view (e.g. Nav Bar)

Table of Contents

Different people have different needs when it comes to seeing a high level "table of contents" of design info. Here are our two main views we're using now:

• ProjectOverviewTable2005
• Design Map

...links (image, feature lists, bugzilla, overview text, schema)

---

Tools available

• tools
  • wiki
  • bugzilla (as a task tracking tool)
  • web server for serving .gif files (http://aloha.osafoundation.org/)
  • other?

• the wiki can
  • show a hierarchical list
  • sort a table -- sort by any column
  • build up an overview page from "included" paragraphs on other pages
  • include gif images on multiple pages
• the wiki cannot
  • filter a table -- return only some rows of a table
  • group a table
  • easily have a unique URL for each row in a table
  • show hierarchical tables (a hierarchical list with table rows for leaf nodes, or a table of rows organized into a hierarchy)

---

Proposals

So, with all of the above considerations in mind, here are a few proposals...

• where to save images
  • We're going to have a lot images (including storyboards, and wireframes, and screenshots). We will often want to include a single image on more than one wiki page.
  • I propose that we keep all the image graphics just as raw .gif files on aloha (or some other web server), rather than using the wiki attachement feature to have the .gif file be stored on the wiki. Jungle.Wiki pages can (and should) still include images by reference.
  • I propose that the .gif files live in some common shared directory, rather than in directories that belong to individual users (like http://aloha.osafoundation.org/~skinner/)
  • I propose that mimi should decide what the file names for look like for individual .gif files. One option would be to have a non-descriptive file name -- for example, the files names could just be serial numbers like 101.gif, 102.gif, 103.gif -- or we could have file names that are just based on the current date, like 2003_12_21_a.gif, 2003_12_21_b.gif, and 2004_02_13_a.gif.

• what document formats to use
  • I propose that we standardize on a small set of file formats, with wiki pages and .gif images as the mainstays.
  • I propose that we stop making any documents as .doc files, or .pdf files, or spreadsheet files, or Notebook files. Chao and Mimi and I are all guilty of occassionally resorting to non-wiki document formats, but I think we should make a real effort not to.

• dot release specs vs. Canoga specs
  • We've talked about different ideas for somehow connecting the dot release specs (like the 0.4 deliverable) to Canoga specs (like the sharing spec). For example, one thing to do would be have the Canoga Sharing spec just be a page with a list of links to the Sharing info in each of the delta specs. Or, another way to do it would be to have the delta spec have a list of features, where each feature was just a link to a feature on the feature list in the Canoga spec.
  • I propose that the dot release specs be independent of the Canoga spec, so that we don't put any effort into maintaining links (and maintaining consistency) between the delta specs and the Canoga spec.
  • I propose that the Canoga specs live on the official Chandler wiki, whereas the delta specs live on the Journal wiki

• Dot-release specs
  • I propose that the dot-release specs look like this one: ZeroPointFourPlanning
    • If possible, just one wiki page per dot release -- (OI: do we also need deliverables for each milestone?)
    • Dot release specs may experience frequent changes as engineering and design group go back and forth about the details
    • After the dot release, the dot release spec is a dead document -- nobody maintains it
    • The delta spec pages are fairly informal and unstructured, at least to start off. The spec page might have images, or tables of features, or long text descriptions, or whatever. We'll create a lot of these deltas, so it's not too important to get the first ones right. We can gradually learn from experience and incrementally improve them to better meet the needs of the engineers who are the consumers of them.
    • Delta specs live on the Journal wiki
    • Some TOC page has links to all the delta specs

• Canoga specs
  • I propose that the Canoga specs look like this one: CanogaSharingDesign
    • Canoga specs are organized by project -- one spec for each project on the standard project list
    • Canoga specs are living documents -- they gradually get improved over time
    • Canoga specs are maintained -- each spec has an assigned "owner" who is responsible for keeping it up to date
    • For each project spec, we have:
      • A feature list -- example: Sharing Feature List
        • a table listing all features and open issues
        • a pointer to a section of the content model
      • A set of images
      • optionally, a historical record of deprecated documents, if there are any
        • old meeting notes
        • sets of questions and answers
        • old working notes
    • Overview materials that span all projects
      • one set of content model documentation -- content model
      • one table of contents page, with pointers to all the design info -- Project Overview Table
      • one glossary page
      • one schedule page
      • one page of usage patterns, perhaps with links to project spec pages -- Canoga Usage Patterns
      • one process summary page, describing the design process

• bugzilla vs. wiki
  • Question: how tightly should we integrate bugzilla tasks and wiki spec features
  • Answer: loosely
  • proposals:
    • I propose that for some information we use both bugzilla and the wiki to keep track of what's going on, even though that means there will be some redundancy and potential for info to get out of sync.
    • I propose that we use the wiki for feature lists, and that we sometimes create bugzilla bugs that map directly to the features in the feature list. The wiki page should focus on describing the feature itself (including info like current design status, and links to images). The corresponding bugzilla entry should focus on describing the task of implementing the feature (including info about who is working on it, how long it will take, etc.). Here's
    • bugzilla info
      • owner -- who's going to implement it
      • release -- what milestone the feature is scheduled for (e.g. 0.3.11)
      • time estimate
      • dependencies -- dependencies on other bugs/tasks/features
      • optional link to the wiki spec page that mentions this feature
    • wiki feature tables (for Canoga feature lists, not delta specs) -- example: CanogaSharingDesign
      • organized into pages by project -- (Calendar, NavBar, etc.)
      • name of feature -- some name for the feature/requirement/open issue/spec item
      • category the feature belongs to -- so that we can group the features on pages that have long lists
      • description
        • optional link to image
        • optional link to bugzilla task
        • optional anchor tag so things can link to this
      • when -- canoga status
        • "done" == already implemented
        • "Canoga"
        • "CanogaWaitlist"
        • "Post-Canoga"
        • "No"
        • "Open Issue"
        • "Open Issue: to be resolved by user testing"
        • "Westwood"
        • "Next Action"
    • Each feature line item in the wiki can have a link that points to the bugzilla entry. We can add those links on a case-by-case when we find them useful. We won't have a special column in the feature list; the bug links can just go in the "description" column
    • The bugzilla entries can have links to spec pages -- again, on a case-by-case basis, if we find them useful. The links won't necessarily point to the wiki feature itself, simply because it's a pain to give each feature on the wiki page its own anchor name.

---

Discussion

• See 18 Dec 2003 meeting notes

Chao: After drafting Projects.CanogaSecurityDesign and starting CanogaSharingDesign20040419, I have two points to offer for discussion:

• Extra constraint: the design team doesn't have all the answers at once. We need to design a document that answers the most important and urgent issues first for design team and apps team constituencies.
• Related to the first point, it may be useful to lay out the documents in a timeline or lifecycle perspective. Which documents are needed for who, when and during which part of our development process.

---

Contributors

• BrianDouglasSkinner - 18 Dec 2003 to 10 Feb 2003