documentation: choosing the right tool for the job

Choosing the Right ToolUser Experience Week 2007 • Washington, DC

Dan BrownPrincipal, EightShapes, LLC

War is bad!

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...

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

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

• 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








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 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


[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



[Client name]










ÿXXX | XXX | XXX

� � � � � ( � �

� � � � � � � � � �

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

� � &� � � #� � � �

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



By Label

By Host










) � � � � " � ��

[page title]

[launch date]

[list of labels]


� � � � � � � � �


[alert title]

[launch date]

[list of labels]






[item title]

[launch date]

[list of labels]

OR

NONE

NONE








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

18



[Client name]










ÿXXX | XXX | XXX

� � � � � ( � �

� � � � � � � � � �

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

� � &� � � #� � � �

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



By Label

By Host










) � � � � " � ��

[page title]

[launch date]

[list of labels]


� � � � � � � � �


[alert title]

[launch date]

[list of labels]






[item title]

[launch date]

[list of labels]

OR

NONE

NONE








18



[Client name]










ÿXXX | XXX | XXX

� � � � � ( � �

� � � � � � � � � �

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

� � &� � � #� � � �

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



By Label

By Host










) � � � � " � ��

[page title]

[launch date]

[list of labels]


� � � � � � � � �


[alert title]

[launch date]

[list of labels]






[item title]

[launch date]

[list of labels]

OR

NONE

NONE








Multiple audiences:• Stakeholders• Technologists

18



[Client name]










ÿXXX | XXX | XXX

� � � � � ( � �

� � � � � � � � � �

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

� � &� � � #� � � �

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



By Label

By Host










) � � � � " � ��

[page title]

[launch date]

[list of labels]


� � � � � � � � �


[alert title]

[launch date]

[list of labels]






[item title]

[launch date]

[list of labels]

OR

NONE

NONE








one audience:

18



[Client name]










ÿXXX | XXX | XXX

� � � � � ( � �

� � � � � � � � � �

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

� � &� � � #� � � �

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



By Label

By Host










) � � � � " � ��

[page title]

[launch date]

[list of labels]


� � � � � � � � �


[alert title]

[launch date]

[list of labels]






[item title]

[launch date]

[list of labels]

OR

NONE

NONE








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

Thanks!Dan [email protected]

www.communicatingdesign.com

mailto:[email protected]

mailto:[email protected]

http://www.communicatingdesign.com

http://www.communicatingdesign.com

documentation: choosing the right tool for the job

Entertainment & Humor

label allby dateby label

label filter

list template

xxxxxx xxxxxx xxxxxx

dateshow pages

page structure

set of pages

campaignname of page