Design Group Meeting, 25 Mar 2004

Attending: MimiYin, ChaoLam, BrianDouglasSkinner, JedBurgess, DavidSurovell, ScottRosenberg

Goals:

• Get feedback from Jed and David about how to make our design documents more useful

---

Pages we walked through

1. SummaryTableViewSpec
2. AdhocCollectionsWorkflow
3. ContactsDesign20040727

---

Feedback we got

"SummaryTableViewSpec"

• Section ordering
  • It would be good to change the order of the sections
    • start with a section like "Motivation" or "Summary" or "Abstract" -- something that answers the question "What is this thing?"
    • then the screenshots section
    • then the open issues section

• Screenshots
  • The screenshots are a good thing. The callout boxes are great. It'd be good to have darker arrow lines from the callout boxes to the things that they refer to.

• Terminology
  • The callout boxes use terms that aren't familiar. It'd be good to have some easy way of finding out what a term means. (For example, what's the "Section" that that the "Item layout selector" refers to?)
  • other examples of terms that aren't immediately available -- OOTB, [IntD], Stamping, Interaction Spec, Visual Spec

• Cryptic bits
  • Sentences are more useful than bullet points.
  • For example, these bullet points are not self-evident:
    • "States: GO, ACT, MD (Selected)"
  • Jed also pointed out this example:
    • Contents
    • Jungle.Items
    • 1 item per row
  • Need more intro context -- would be good to start each section with a high-level description of what the thing is -- for example, the "Fish-eye timestamp" could use an intro.

• How much is enough?
  • The documents are far from comprehensive. And they'll have to be far from comprehensive unless they're really long. Do we want them to be really long? Do we want them to be comprehensive?
  • Jed suggests that it's okay to start with something that gives a general flavor, and then resolve the details as they come up. It'd be good to document each decision made along the way.

"ExplicitCollectionsWorkflow"

• Document order
  • Makes sense to look at this doc first, and then the "SummaryTableViewSpec" -- present workflows first, then component specs -- start with concepts, then go to specifics

• Terminology
  • Jed: "every eight word is something I don't know"
    • examples: thrask, cluster, MD, floating collection
  • solutions?
    • one solution would be to have a terminology section at the start of every doc
    • another solution would be to have links from individual words to glossary pages

"ContactsDesign"

• Feature lists
  • It's nice to have a document like this that provides a checklist of everything that needs to be done.
  • However, the checklist is very high level, and doesn't give details about how each thing ought to be done. It'd be good to have wireframes that show what the features will look like.

Bringing the documents together

• Document roles
  • Jed found the workflow document (AdhocCollectionsWorkflow) more useful than eithe the component spec (SummaryTableViewSpec) or the feature list (ContactsDesign20040727)
  • Jed likes our idea of trying to merge the workflows and feature lists into one document type.

• Organizing features via wireframes
  • Jed's favorite part of the documents was the wireframe diagrams with the callout boxes. He thought it might work out well to try to have the feature lists organized in terms of the callout boxes. So, the wireframe would be a starting point (or Table of Contents), and from there you could get to checklists of all the features.

Biggest holes

• Interaction specs
  • Mimi noted that from talking to Jed it seemed like one of the biggest gaping holes in the docs was the lack of detailed interaction specs.

• Content model mapping
  • Another big missing piece was some sort of mapping to the content model. Some kind of documentation that would map from the things in a wireframe to the attributes in the content model, or from the concepts in the user's cognitive model to the kinds and attributes in the content model.

• Cross-team dialog
  • Another thing we recognized the need for was some way to capture the ongoing design that gets done after the design group first drafts a document. After the first draft goes to engineering, there's a back and forth dialog between design and engineering. It'd be good to have the design docs be living documents that capture this dialog. Maybe we should have sections in the docs for "developer questions" or "developer assumptions", where engineers can add to the docs as they're working from them.

---

• BrianDouglasSkinner - 30 Mar 2004