Documentation: Choosing the Right Tool for the Job

Slide 1: Choosing the Right Tool User Experience Week 2007 • Washington, DC Dan Brown Principal, EightShapes, LLC

Slide 2: 2

Slide 4: War is bad!

Slide 5: 5

Slide 6: Longitude Latitude Number of troops Direction Time Temperature 5

Slide 7: • Define • Elaborate • Enhance

Slide 8: Anchors Steps Paths Decision Points • Define Step Distinctions Step Variations • Elaborate Step Groupings Step Details • Enhance Error Paths Triggers Scenarios etc...

Slide 9: Anchors Steps Paths Decision Points • Define Step Distinctions Step Variations • Elaborate Step Groupings Step Details • Enhance Error Paths Triggers Scenarios etc...

Slide 10: 7

Slide 11: 8

Slide 12: 9

Slide 13: Choice of Moment ❖ ❖ Choice of Frame ❖ Choice of Image ❖ Choice of Word ❖ Choice of Flow 10

Slide 14: From BPRD: Garden of Souls #5 © Dark Horse Comics 11

Slide 18: From Fallen Son: Iron Man #5 © Marvel Comics 12

Slide 19: From New Avengers #32 © Marvel Comics 13

Slide 21: What aspects of the user What level of detail are How are you going to experience are you going you going to show? represent abstract to show? concepts? From Making Comics © 2006 Scott McCloud How are you going to How are you going to work describe the experience? within the constraints of the medium? 14

Slide 22: • Purpose of document • Document’s audience • Project context • Information on-hand

Slide 23: 16

Slide 24: Document detailed interactions • • Account for different user groups • Show business rules • Prioritize steps in flow 16

Slide 25: Aspects = steps, decisions, errors • • Detail = medium • Description = labeling • Abstraction = high • Constraints = swimlanes 16

Slide 26: ॰‫ ݏ‬ԏ ৺ӹ৺ ‫ݏ‬ XXXXXX > XXXXXX > XXXXXX • The LIST TEMPLATE provides a page structure for ÿ XXX | XXX | XXX displaying lists of objects--campaigns, pages, or alerts. • Each campaign has lists dedicated to pages and alerts. XXXXXXXXX XXX | XXX | XXX • Each campaign also has a \"watchlist\", rendered in the same XXXXXXXXX XXX | XXX | XXX template, that combines both pages and alerts. XXXXXXXXX XXX | XXX | XXX • Users may add pages and alerts to the watchlist, though a XXXXXXXXX XXX | XXX | XXX campaign's watchlist is shared by all users of the system. XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX & & & ) \" [Client name] [Client name] [Campaign name] [Client name] [Campaign name] [Client name] Watchlist ( Active By Label By Host All By Visits By Date By Label All By Date By Label All NONE Compare Export Label Compare Export Label Compare Export Label Compare Export Label By Label Filter by label: select label... By Date Show pages launched on: mm/dd/yyyy By Date Show alerts launched on: mm/dd/yyyy NONE By Host Filter by host: select host... By Label Filter by label: select label... By Label Filter by label: select label... &# [Name of Campaign] [Name of Page] [Name of Alert] [launch date] [Name of Item] watch list alerts list page list [launch date] add to/remove from watchlist [launch date] add to/remove from watchlist remove from watchlist [page title] [alert title] [item title] OR [list of labels] [list of labels] [list of labels] Grassroots Enterprises Dan Brown client: prepared by: Reports Module Redesign Thu Feb 22 2007 project: date: Page 4 of 5 Speci cation 1.0 document: version: 17

Slide 27: ॰‫ ݏ‬ԏ ৺ӹ৺ ‫ݏ‬ XXXXXX > XXXXXX > XXXXXX • The LIST TEMPLATE provides a page structure for ÿ XXX | XXX | XXX displaying lists of objects--campaigns, pages, or alerts. • Each campaign has lists dedicated to pages and alerts. XXXXXXXXX XXX | XXX | XXX • Each campaign also has a \"watchlist\", rendered in the same XXXXXXXXX XXX | XXX | XXX template, that combines both pages and alerts. XXXXXXXXX XXX | XXX | XXX • Users may add pages and alerts to the watchlist, though a XXXXXXXXX XXX | XXX | XXX campaign's watchlist is shared by all users of the system. XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX & & & ) \" [Client name] [Client name] [Campaign name] [Client name] [Campaign name] [Client name] Watchlist ( Active By Label By Host All By Visits By Date By Label All By Date By Label All NONE Compare Export Label Compare Export Label Compare Export Label Compare Export Label By Label Filter by label: select label... By Date Show pages launched on: mm/dd/yyyy By Date Show alerts launched on: mm/dd/yyyy NONE By Host Filter by host: select host... By Label Filter by label: select label... By Label Filter by label: select label... Aspects = set of pages • &# [Name of Campaign] [Name of Page] [Name of Alert] [launch date] [Name of Item] watch list alerts list page list [launch date] add to/remove from watchlist [launch date] add to/remove from watchlist remove from watchlist [page title] [alert title] [item title] OR • Detail = high [list of labels] [list of labels] [list of labels] • Description = minimal • Abstraction = A LOT • Constraints = highly abstract, limit detail Grassroots Enterprises Dan Brown client: prepared by: Reports Module Redesign Thu Feb 22 2007 project: date: Page 4 of 5 Speci cation 1.0 document: version: 17

Slide 28: ॰‫ ݏ‬ԏ ৺ӹ৺ ‫ݏ‬ XXXXXX > XXXXXX > XXXXXX • The LIST TEMPLATE provides a page structure for ÿ XXX | XXX | XXX displaying lists of objects--campaigns, pages, or alerts. • Each campaign has lists dedicated to pages and alerts. XXXXXXXXX XXX | XXX | XXX • Each campaign also has a \"watchlist\", rendered in the same XXXXXXXXX XXX | XXX | XXX template, that combines both pages and alerts. XXXXXXXXX XXX | XXX | XXX • Users may add pages and alerts to the watchlist, though a XXXXXXXXX XXX | XXX | XXX campaign's watchlist is shared by all users of the system. XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX & & & [Client name] [Client name] [Campaign name] [Client name] [Campaign name] ( Active By Label By Host All By Visits By Date By Label All By Date By Label All Compare Export Label Compare Export Label Compare Export Label By Label Filter by label: select label... By Date Show pages launched on: mm/dd/yyyy By Date Show alerts launche By Host Filter by host: select host... By Label Filter by label: select label... By Label Filter by label: sele &# [Name of Campaign] [Name of Page] [Name of Alert] watch list alerts list page list [launch date] add to/remove from watchlist [launch date] [page title] [alert title] [list of labels] [list of labels] 18

Slide 29: ॰‫ ݏ‬ԏ ৺ӹ৺ ‫ݏ‬ XXXXXX > XXXXXX > XXXXXX • The LIST TEMPLATE provides a page structure for ÿ XXX | XXX | XXX displaying lists of objects--campaigns, pages, or alerts. • Each campaign has lists dedicated to pages and alerts. XXXXXXXXX XXX | XXX | XXX • Each campaign also has a \"watchlist\", rendered in the same XXXXXXXXX XXX | XXX | XXX template, that combines both pages and alerts. XXXXXXXXX XXX | XXX | XXX • Users may add pages and alerts to the watchlist, though a XXXXXXXXX XXX | XXX | XXX campaign's watchlist is shared by all users of the system. XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX & & & [Client name] [Client name] [Campaign name] [Client name] [Campaign name] ( Active By Label By Host All By Visits By Date By Label All By Date By Label All Compare Export Label Compare Export Label Compare Export Label Multiple audiences: By Label Filter by label: select label... By Date Show pages launched on: mm/dd/yyyy By Date Show alerts launche • Stakeholders By Host Filter by host: select host... By Label Filter by label: select label... By Label Filter by label: sele • Technologists &# [Name of Campaign] [Name of Page] [Name of Alert] watch list alerts list page list [launch date] add to/remove from watchlist [launch date] [page title] [alert title] [list of labels] [list of labels] 18

Slide 30: ॰‫ ݏ‬ԏ ৺ӹ৺ ‫ݏ‬ XXXXXX > XXXXXX > XXXXXX • The LIST TEMPLATE provides a page structure for ÿ XXX | XXX | XXX displaying lists of objects--campaigns, pages, or alerts. • Each campaign has lists dedicated to pages and alerts. XXXXXXXXX XXX | XXX | XXX • Each campaign also has a \"watchlist\", rendered in the same XXXXXXXXX XXX | XXX | XXX template, that combines both pages and alerts. XXXXXXXXX XXX | XXX | XXX • Users may add pages and alerts to the watchlist, though a XXXXXXXXX XXX | XXX | XXX campaign's watchlist is shared by all users of the system. XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX & & & [Client name] [Client name] [Campaign name] [Client name] [Campaign name] ( Active By Label By Host All By Visits By Date By Label All By Date By Label All Compare Export Label Compare Export Label Compare Export Label one audience: By Label Filter by label: select label... By Date Show pages launched on: mm/dd/yyyy By Date Show alerts launche By Host Filter by host: select host... By Label Filter by label: select label... By Label Filter by label: sele &# [Name of Campaign] [Name of Page] [Name of Alert] watch list alerts list page list [launch date] add to/remove from watchlist [launch date] [page title] [alert title] [list of labels] [list of labels] 18

Slide 31: ॰‫ ݏ‬ԏ ৺ӹ৺ ‫ݏ‬ XXXXXX > XXXXXX > XXXXXX • The LIST TEMPLATE provides a page structure for ÿ XXX | XXX | XXX displaying lists of objects--campaigns, pages, or alerts. • Each campaign has lists dedicated to pages and alerts. XXXXXXXXX XXX | XXX | XXX • Each campaign also has a \"watchlist\", rendered in the same XXXXXXXXX XXX | XXX | XXX template, that combines both pages and alerts. XXXXXXXXX XXX | XXX | XXX • Users may add pages and alerts to the watchlist, though a XXXXXXXXX XXX | XXX | XXX campaign's watchlist is shared by all users of the system. XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX XXXXXXXXX XXX | XXX | XXX & & & [Client name] [Client name] [Campaign name] [Client name] [Campaign name] ( Active By Label By Host All By Visits By Date By Label All By Date By Label All Compare Export Label Compare Export Label Compare Export Label one audience: By Label Filter by label: select label... By Date Show pages launched on: mm/dd/yyyy By Date Show alerts launche By Host Filter by host: select host... By Label Filter by label: select label... By Label Filter by label: sele •ME &# [Name of Campaign] [Name of Page] [Name of Alert] watch list alerts list page list [launch date] add to/remove from watchlist [launch date] [page title] [alert title] [list of labels] [list of labels] 18

Slide 32: Purpose = explain business rules • Audience = stakeholders, technologists, others? • Context = requirements elicitation • Information = meeting notes •

Slide 33: Aspect = rules constraining interactions • Detail = as much as possible • Describe = rule “headline” and details • Abstractions = visualize • Constraints = incorporate pictures •

Slide 34: Unused activation Passes expire at 23:59 CT Activation codes expire Client can create passes codes expire after on the third day after after one use. for distribution. predetermined date. activation. Passes may be created by either the Marketing Su M T W Th F Sa Department or Customer Service, and each will be coded uniquely for tracking purposes. Passes created by Client may break any of the rules in this row (expiration and duration). Pass Activated Here Pass Expires Here The system will be exible so Client can create passes The system will be exible so Client can create codes The system will be exible so Client can create passes that can be used more than one. that have longer lifespans. that last longer than three days. Every pass is a \"child\" Guest registrations share Subscribers are allowed All dates and times are account assigned to a the namespace with ve invitations a day. in Central Time. \"super-parent\" account. regular subscriptions Tuesday Wednesday Thursday CHILD CHILD SUBSCRIBER CHILD GUEST SUPER PARENT CHILD CHILD NAMESPACE CHILD 21

Slide 35: ion Passes expire at 23:59 CT Client ter on the third day after fo ate. activation. Passes may Su M T W Th F Sa Department o coded u Passes created this ro Pass Activated Here Pass Expires Here n create codes The system will be exible so Client can create passes s. that last longer than three days. Every pass is a \"child\" owed All da 22

Slide 36: Purpose = define scope of content • Audience = stakeholders, money • Context = direction-setting • Information = none •

Slide 37: Aspect = relationship between key content • Detail = as little as possible • Describe = label concepts • Abstractions = line formatting, color coding • Constraints = limit depth and detail •

Slide 38: 25

Slide 39: Thanks! Dan Brown dan@eightshapes.com www.communicatingdesign.com

Slideshare.net (beta)