Documentation: Choosing the Right Tool for the Job

Post on 28-Jan-2015

113 views 1 download

Tags:

description

 

Transcript of Documentation: Choosing the Right Tool for the Job

Choosing the Right ToolUser Experience Week 2007 • Washington, DC

Dan BrownPrincipal, EightShapes, LLC

2

War is bad!

5

5

Number of troops

TemperatureTime

Latitude

Longitude

Direction

• Define• Elaborate• Enhance

• Define• Elaborate• Enhance

Anchors

Steps

Paths

Decision Points

Step Distinctions

Step Variations

Step Groupings

Step Details

Error Paths

Triggers

Scenarios

etc...

• Define• Elaborate• Enhance

Anchors

Steps

Paths

Decision Points

Step Distinctions

Step Variations

Step Groupings

Step Details

Error Paths

Triggers

Scenarios

etc...

7

8

9

10

❖Choice of Moment❖Choice of Frame❖Choice of Image❖Choice of Word❖Choice of Flow

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

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

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

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

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

13From New Avengers #32 © Marvel Comics

14

From

Mak

ing

Com

ics ©

200

6 Sc

ott M

cClo

ud

14

What aspects of the user experience are you going

to show?

What level of detail are you going to show?

How are you going to represent abstract

concepts?

How are you going to describe the experience?

How are you going to work within the constraints of

the medium? From

Mak

ing

Com

ics ©

200

6 Sc

ott M

cClo

ud

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

16

16

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

16

• Aspects = steps, decisions, errors• Detail = medium• Description = labeling• Abstraction = high• Constraints = swimlanes

17

prepared by: Dan Browndate: Thu Feb 22 2007version: 1.0 Page 4 of 5

client: Grassroots Enterprisesproject: Reports Module Redesigndocument: Speci�cation

[Client name]

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

4॰৺ӹ85ݏԏ৺ݏ

ÿXXX | XXX | XXX

� � � � � ( � �

� � � � � � � � � �

� � � � � � � � � � � �

� � &� � � #� � � �

&� � � � � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � �

Active By Label By Host All

Compare Export Label

By Label

By Host

Filter by label: select label...

Filter by host: select host...

[Name of Campaign] page listalerts listwatch list

By Visits By Date By Label All By Date By Label All

By Label Filter by label: select label...

By Date Show pages launched on: mm/dd/yyyy

By Label Filter by label: select label...

By Date Show alerts launched on: mm/dd/yyyy

[Name of Page] add to/remove from watchlist

) � � � � " � �� � � � � � � � � � � � � � � � � � � � � � �

[page title]

[launch date]

[list of labels]

XXXXXX > XXXXXX > XXXXXX�

� � � � � � � � �

[Name of Alert] add to/remove from watchlist

[alert title]

[launch date]

[list of labels]

[Client name] [Campaign name]

Compare Export Label Compare Export Label

[Client name] [Campaign name] [Client name] Watchlist

Compare Export Label

[Name of Item] remove from watchlist

[item title]

[launch date]

[list of labels]

OR

NONE

NONE

• The LIST TEMPLATE provides a page structure for

displaying lists of objects--campaigns, pages, or alerts.

• Each campaign has lists dedicated to pages and alerts.

• Each campaign also has a "watchlist", rendered in the same

template, that combines both pages and alerts.

• Users may add pages and alerts to the watchlist, though a

campaign's watchlist is shared by all users of the system.

17

prepared by: Dan Browndate: Thu Feb 22 2007version: 1.0 Page 4 of 5

client: Grassroots Enterprisesproject: Reports Module Redesigndocument: Speci�cation

[Client name]

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

4॰৺ӹ85ݏԏ৺ݏ

ÿXXX | XXX | XXX

� � � � � ( � �

� � � � � � � � � �

� � � � � � � � � � � �

� � &� � � #� � � �

&� � � � � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � �

Active By Label By Host All

Compare Export Label

By Label

By Host

Filter by label: select label...

Filter by host: select host...

[Name of Campaign] page listalerts listwatch list

By Visits By Date By Label All By Date By Label All

By Label Filter by label: select label...

By Date Show pages launched on: mm/dd/yyyy

By Label Filter by label: select label...

By Date Show alerts launched on: mm/dd/yyyy

[Name of Page] add to/remove from watchlist

) � � � � " � �� � � � � � � � � � � � � � � � � � � � � � �

[page title]

[launch date]

[list of labels]

XXXXXX > XXXXXX > XXXXXX�

� � � � � � � � �

[Name of Alert] add to/remove from watchlist

[alert title]

[launch date]

[list of labels]

[Client name] [Campaign name]

Compare Export Label Compare Export Label

[Client name] [Campaign name] [Client name] Watchlist

Compare Export Label

[Name of Item] remove from watchlist

[item title]

[launch date]

[list of labels]

OR

NONE

NONE

• The LIST TEMPLATE provides a page structure for

displaying lists of objects--campaigns, pages, or alerts.

• Each campaign has lists dedicated to pages and alerts.

• Each campaign also has a "watchlist", rendered in the same

template, that combines both pages and alerts.

• Users may add pages and alerts to the watchlist, though a

campaign's watchlist is shared by all users of the system.

• Aspects = set of pages• Detail = high• Description = minimal• Abstraction = A LOT• Constraints = highly abstract, limit detail

18

prepared by: Dan Browndate: Thu Feb 22 2007version: 1.0 Page 4 of 5

client: Grassroots Enterprisesproject: Reports Module Redesigndocument: Speci�cation

[Client name]

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

4॰৺ӹ85ݏԏ৺ݏ

ÿXXX | XXX | XXX

� � � � � ( � �

� � � � � � � � � �

� � � � � � � � � � � �

� � &� � � #� � � �

&� � � � � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � �

Active By Label By Host All

Compare Export Label

By Label

By Host

Filter by label: select label...

Filter by host: select host...

[Name of Campaign] page listalerts listwatch list

By Visits By Date By Label All By Date By Label All

By Label Filter by label: select label...

By Date Show pages launched on: mm/dd/yyyy

By Label Filter by label: select label...

By Date Show alerts launched on: mm/dd/yyyy

[Name of Page] add to/remove from watchlist

) � � � � " � �� � � � � � � � � � � � � � � � � � � � � � �

[page title]

[launch date]

[list of labels]

XXXXXX > XXXXXX > XXXXXX�

� � � � � � � � �

[Name of Alert] add to/remove from watchlist

[alert title]

[launch date]

[list of labels]

[Client name] [Campaign name]

Compare Export Label Compare Export Label

[Client name] [Campaign name] [Client name] Watchlist

Compare Export Label

[Name of Item] remove from watchlist

[item title]

[launch date]

[list of labels]

OR

NONE

NONE

• The LIST TEMPLATE provides a page structure for

displaying lists of objects--campaigns, pages, or alerts.

• Each campaign has lists dedicated to pages and alerts.

• Each campaign also has a "watchlist", rendered in the same

template, that combines both pages and alerts.

• Users may add pages and alerts to the watchlist, though a

campaign's watchlist is shared by all users of the system.

18

prepared by: Dan Browndate: Thu Feb 22 2007version: 1.0 Page 4 of 5

client: Grassroots Enterprisesproject: Reports Module Redesigndocument: Speci�cation

[Client name]

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

4॰৺ӹ85ݏԏ৺ݏ

ÿXXX | XXX | XXX

� � � � � ( � �

� � � � � � � � � �

� � � � � � � � � � � �

� � &� � � #� � � �

&� � � � � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � �

Active By Label By Host All

Compare Export Label

By Label

By Host

Filter by label: select label...

Filter by host: select host...

[Name of Campaign] page listalerts listwatch list

By Visits By Date By Label All By Date By Label All

By Label Filter by label: select label...

By Date Show pages launched on: mm/dd/yyyy

By Label Filter by label: select label...

By Date Show alerts launched on: mm/dd/yyyy

[Name of Page] add to/remove from watchlist

) � � � � " � �� � � � � � � � � � � � � � � � � � � � � � �

[page title]

[launch date]

[list of labels]

XXXXXX > XXXXXX > XXXXXX�

� � � � � � � � �

[Name of Alert] add to/remove from watchlist

[alert title]

[launch date]

[list of labels]

[Client name] [Campaign name]

Compare Export Label Compare Export Label

[Client name] [Campaign name] [Client name] Watchlist

Compare Export Label

[Name of Item] remove from watchlist

[item title]

[launch date]

[list of labels]

OR

NONE

NONE

• The LIST TEMPLATE provides a page structure for

displaying lists of objects--campaigns, pages, or alerts.

• Each campaign has lists dedicated to pages and alerts.

• Each campaign also has a "watchlist", rendered in the same

template, that combines both pages and alerts.

• Users may add pages and alerts to the watchlist, though a

campaign's watchlist is shared by all users of the system.

Multiple audiences:• Stakeholders• Technologists

18

prepared by: Dan Browndate: Thu Feb 22 2007version: 1.0 Page 4 of 5

client: Grassroots Enterprisesproject: Reports Module Redesigndocument: Speci�cation

[Client name]

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

4॰৺ӹ85ݏԏ৺ݏ

ÿXXX | XXX | XXX

� � � � � ( � �

� � � � � � � � � �

� � � � � � � � � � � �

� � &� � � #� � � �

&� � � � � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � �

Active By Label By Host All

Compare Export Label

By Label

By Host

Filter by label: select label...

Filter by host: select host...

[Name of Campaign] page listalerts listwatch list

By Visits By Date By Label All By Date By Label All

By Label Filter by label: select label...

By Date Show pages launched on: mm/dd/yyyy

By Label Filter by label: select label...

By Date Show alerts launched on: mm/dd/yyyy

[Name of Page] add to/remove from watchlist

) � � � � " � �� � � � � � � � � � � � � � � � � � � � � � �

[page title]

[launch date]

[list of labels]

XXXXXX > XXXXXX > XXXXXX�

� � � � � � � � �

[Name of Alert] add to/remove from watchlist

[alert title]

[launch date]

[list of labels]

[Client name] [Campaign name]

Compare Export Label Compare Export Label

[Client name] [Campaign name] [Client name] Watchlist

Compare Export Label

[Name of Item] remove from watchlist

[item title]

[launch date]

[list of labels]

OR

NONE

NONE

• The LIST TEMPLATE provides a page structure for

displaying lists of objects--campaigns, pages, or alerts.

• Each campaign has lists dedicated to pages and alerts.

• Each campaign also has a "watchlist", rendered in the same

template, that combines both pages and alerts.

• Users may add pages and alerts to the watchlist, though a

campaign's watchlist is shared by all users of the system.

one audience:

18

prepared by: Dan Browndate: Thu Feb 22 2007version: 1.0 Page 4 of 5

client: Grassroots Enterprisesproject: Reports Module Redesigndocument: Speci�cation

[Client name]

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

XXXXXXXXX XXX | XXX | XXX

4॰৺ӹ85ݏԏ৺ݏ

ÿXXX | XXX | XXX

� � � � � ( � �

� � � � � � � � � �

� � � � � � � � � � � �

� � &� � � #� � � �

&� � � � � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � &� � � � � � � � � � � � � � � � � � � � � �

Active By Label By Host All

Compare Export Label

By Label

By Host

Filter by label: select label...

Filter by host: select host...

[Name of Campaign] page listalerts listwatch list

By Visits By Date By Label All By Date By Label All

By Label Filter by label: select label...

By Date Show pages launched on: mm/dd/yyyy

By Label Filter by label: select label...

By Date Show alerts launched on: mm/dd/yyyy

[Name of Page] add to/remove from watchlist

) � � � � " � �� � � � � � � � � � � � � � � � � � � � � � �

[page title]

[launch date]

[list of labels]

XXXXXX > XXXXXX > XXXXXX�

� � � � � � � � �

[Name of Alert] add to/remove from watchlist

[alert title]

[launch date]

[list of labels]

[Client name] [Campaign name]

Compare Export Label Compare Export Label

[Client name] [Campaign name] [Client name] Watchlist

Compare Export Label

[Name of Item] remove from watchlist

[item title]

[launch date]

[list of labels]

OR

NONE

NONE

• The LIST TEMPLATE provides a page structure for

displaying lists of objects--campaigns, pages, or alerts.

• Each campaign has lists dedicated to pages and alerts.

• Each campaign also has a "watchlist", rendered in the same

template, that combines both pages and alerts.

• Users may add pages and alerts to the watchlist, though a

campaign's watchlist is shared by all users of the system.

one audience:

•ME

• Purpose = explain business rules

• Audience = stakeholders, technologists, others?

• Context = requirements elicitation

• Information = meeting notes

• Aspect = rules constraining interactions

• Detail = as much as possible

• Describe = rule “headline” and details

• Abstractions = visualize

• Constraints = incorporate pictures

21

ThursdayTuesday

Activation codes expire after one use.

Unused activation codes expire after

predetermined date.

Passes expire at 23:59 CT on the third day after

activation. Su M T W Th F Sa

Pass Activated Here Pass Expires Here

All dates and times are in Central Time.

Guest registrations share the namespace with regular subscriptions

$�

GUESTSUBSCRIBER

NAMESPACE

The system will be !exible so Client can create passes that can be used more than one.

The system will be !exible so Client can create codes that have longer lifespans.

The system will be !exible so Client can create passes that last longer than three days.

Wednesday

Subscribers are allowed "ve invitations a day.

SUPER PARENT

Every pass is a "child" account assigned to a

"super-parent" account.

CHILD

CHILD

CHILD

CHILD

CHILD

CHILD

Client can create passes for distribution.

Passes may be created by either the Marketing 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).

22

ThursdayTuesday

Activation codes expire after one use.

Unused activation codes expire after

predetermined date.

Passes expire at 23:59 CT on the third day after

activation. Su M T W Th F Sa

Pass Activated Here Pass Expires Here

All dates and times are in Central Time.

Guest registrations share the namespace with regular subscriptions

$�

GUESTSUBSCRIBER

NAMESPACE

The system will be !exible so Client can create passes that can be used more than one.

The system will be !exible so Client can create codes that have longer lifespans.

The system will be !exible so Client can create passes that last longer than three days.

Wednesday

Subscribers are allowed "ve invitations a day.

SUPER PARENT

Every pass is a "child" account assigned to a

"super-parent" account.

CHILD

CHILD

CHILD

CHILD

CHILD

CHILD

Client can create passes for distribution.

Passes may be created by either the Marketing 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).

• Purpose = define scope of content

• Audience = stakeholders, money

• Context = direction-setting

• Information = none

• Aspect = relationship between key content

• Detail = as little as possible

• Describe = label concepts

• Abstractions = line formatting, color coding

• Constraints = limit depth and detail

25