Stop Documenting,Start Designing!

How to get out of the traditional documentation box

Jim Smith and Vivian AschwandenPlatform Computing Corporation

Session description Session description (from LavaCon program)(from LavaCon program)• A goal we should not forget as information A goal we should not forget as information

developers/technical communicators (or whatever you want to developers/technical communicators (or whatever you want to call those who create documentation, literature, content for call those who create documentation, literature, content for their company’s products) should be to design information. their company’s products) should be to design information.

• Designing information, like designing software or a Designing information, like designing software or a manufactured item or even a house, requires planning and manufactured item or even a house, requires planning and time spent doing architectural design. We need to stop time spent doing architectural design. We need to stop “documenting a product” and start “designing information” so “documenting a product” and start “designing information” so that needed information is presented to users where/when it’s that needed information is presented to users where/when it’s needed.needed.

• This is not a new message. But it is a call to revisit what should This is not a new message. But it is a call to revisit what should be the loftier goal of technical communicators, and to make a be the loftier goal of technical communicators, and to make a shift in our thinking, approach, and implementation of user shift in our thinking, approach, and implementation of user information.information.

Where we will go todayWhere we will go today

• About usAbout us• Management contextManagement context• Designing vs. documentingDesigning vs. documenting

– What changes, what doesn’tWhat changes, what doesn’t– What does it mean? How, why, obstaclesWhat does it mean? How, why, obstacles

• Some examplesSome examples• Our experiencesOur experiences• Final thoughts & takeawaysFinal thoughts & takeaways

Jim and VivianJim and Vivian

Jim SmithJim Smith• Technical Technical

Communicator, 20+ yrs, Communicator, 20+ yrs, including —including —– 7 at IBM7 at IBM– 11 at Platform Computing11 at Platform Computing– 2 as Manager of ID/UX 2 as Manager of ID/UX

Team at PlatformTeam at Platform

• Starting PhD in Starting PhD in Linguistics at University Linguistics at University of Torontoof Toronto

• jsmith@platform.comjsmith@platform.com

Vivian AschwandenVivian Aschwanden

• Technical Communicator, Technical Communicator, 13 yrs, including —13 yrs, including —– 7 at Leitch/Harris 7 at Leitch/Harris

Broadcasting; 3 as group Broadcasting; 3 as group leaderleader

– 6 at Platform Computing6 at Platform Computing

• Current roles: Current roles: – F/T senior IDF/T senior ID– P/T program manager P/T program manager

(CAPM)(CAPM)

• vaschwan@platform.comvaschwan@platform.com

44

What we doWhat we do

• Information Development at Platform Information Development at Platform Computing:Computing:– Plans, designs, writes, delivers user Plans, designs, writes, delivers user

documentation for all Platform software documentation for all Platform software productsproducts

– Participates fully in all phases of product Participates fully in all phases of product development from initial product development from initial product requirements, to user experience requirements, to user experience design, to packaging and deliverydesign, to packaging and delivery

Platform ComputingPlatform Computing

• Platform Computing is the leader in Platform Computing is the leader in cluster, grid and cloud management cluster, grid and cloud management software with:software with:– 2,000 customers in nearly every high 2,000 customers in nearly every high

performance computing environmentperformance computing environment– 5 million CPUs under management5 million CPUs under management– Strategic relationships with Cray, Dell, HP, Strategic relationships with Cray, Dell, HP,

IBM, Intel, Microsoft, Red Hat and SASIBM, Intel, Microsoft, Red Hat and SAS– 530 professionals working across 10 global 530 professionals working across 10 global

centerscenters– More than 100 application partnerships for More than 100 application partnerships for

cluster, grid, and cloud enablementcluster, grid, and cloud enablement

Spoiler alert – how the story Spoiler alert – how the story endsends

• FirstFirst think about: think about:– Where Where and and whenwhen users need information users need information– How How to let users stay in their taskto let users stay in their task– HowHow the pieces you already know exist fit the pieces you already know exist fit

together to make a coherent together to make a coherent user user assistance system assistance system in the product in the product

• ThenThen think about think about whatwhat to write (if to write (if anything)anything)

Management contextManagement context

• Strategic direction change for Strategic direction change for information development – move from information development – move from command-line product to web applicationcommand-line product to web application

• New markets, new customersNew markets, new customers

• Required new product and Required new product and documentation strategiesdocumentation strategies

• Fewer team resourcesFewer team resources

• Faster product release cyclesFaster product release cycles

Photo: stop by evaporatedPhoto: stop by evaporated

How to stop documenting…How to stop documenting…

• Not stopping permanently, like driving up to a Not stopping permanently, like driving up to a stop sign: we stop, look around, decide which stop sign: we stop, look around, decide which way to go then move aheadway to go then move ahead

• For users to succeed, need to identify user For users to succeed, need to identify user information needs, and design to that information needs, and design to that

- For new products to succeed need to do look at For new products to succeed need to do look at all aspects of development and designall aspects of development and design

- Focus on entire user experience - put in Focus on entire user experience - put in processes and software tools/libraries/patterns processes and software tools/libraries/patterns to avoid hand crafting each page for each to avoid hand crafting each page for each productproduct

copyright ©2006 - 2009 by DesignForYourWine.com.®copyright ©2006 - 2009 by DesignForYourWine.com.®

And start designing …And start designing …

• Be bold – put a stake in the ground and say no- Be bold – put a stake in the ground and say no- I'm not documenting anything until the UX design I'm not documenting anything until the UX design is rightis right

• Resist the impulse to start documenting Resist the impulse to start documenting immediately – take the chance to get deeply immediately – take the chance to get deeply involved in understanding workflow and involved in understanding workflow and information architecture information architecture

• Gaps in the user interaction are a red flag to gaps Gaps in the user interaction are a red flag to gaps in the design – push to fix the design rather than in the design – push to fix the design rather than document around the gapdocument around the gap

• Get involved elsewhere in the building – if do find Get involved elsewhere in the building – if do find you need document, you already know where you need document, you already know where information should go and how much to writeinformation should go and how much to write

What changes?What changes?

• Reviewing different kinds of design Reviewing different kinds of design documents with a different focusdocuments with a different focus

• Starting to write conventional Starting to write conventional documentation as late as possibledocumentation as late as possible

• Communicating with users more Communicating with users more through the GUI than the through the GUI than the documentationdocumentation

• Focusing effort on filling gaps in user Focusing effort on filling gaps in user interactioninteraction

What stays the same?What stays the same?

• Same raw materials: words on a Same raw materials: words on a pagepage

• Still review developer specifications Still review developer specifications and feature design documents, but and feature design documents, but not extracting feature/functionality not extracting feature/functionality info for user guidesinfo for user guides

• Use design specifications for info to Use design specifications for info to expose in the UIexpose in the UI

Design – what does it Design – what does it mean?mean?• SeamlessSeamless end-user assistanceend-user assistance• Low impact Low impact on user goalson user goals• ImmediateImmediate help – users not taken out of help – users not taken out of

current taskcurrent task• IntegratedIntegrated transparently in GUI – users transparently in GUI – users

won’t even think of it as helpwon’t even think of it as help• MinimalMinimal standalone documentation standalone documentation• Online help content Online help content searchable searchable and and

context-sensitivecontext-sensitive• Does not Does not eliminate need for conventional eliminate need for conventional

helphelp

Design – how is it done?Design – how is it done?

• Enabled by cross-functional design teamEnabled by cross-functional design team

• Involvement at earliest pointInvolvement at earliest point

• Instead of describing features, we own all Instead of describing features, we own all the words in the UIthe words in the UI

• Most content already exists in other Most content already exists in other product documentation – reuse in smaller product documentation – reuse in smaller help topicshelp topics

• Effort shifts to putting user assistance Effort shifts to putting user assistance directly in the product UIdirectly in the product UI

Design – why do it?Design – why do it?

•Designed information benefits Designed information benefits usersusers::– Supports “inadvertent learning”Supports “inadvertent learning”– Users are less aware they’re getting “help” Users are less aware they’re getting “help”

– the entire UI becomes literally “helpful”– the entire UI becomes literally “helpful”– Encourages explorationEncourages exploration– Increases customer success without being Increases customer success without being

a time-wasting distractiona time-wasting distraction

Design – why do it?Design – why do it?

• Designed information benefits Designed information benefits writerswriters::– Enables focus on the potential user “pain Enables focus on the potential user “pain

points”points”– Less conventional procedural (“How do Less conventional procedural (“How do

I?”) documentationI?”) documentation– Integrated into GUI code as part of the UIIntegrated into GUI code as part of the UI– Designed at same time as overall user Designed at same time as overall user

experienceexperience

Design – any obstacles?Design – any obstacles?

• Making room on the screen for user Making room on the screen for user assistance contentassistance content

• Writing reusable content for Writing reusable content for documents, GUI and messages etc.documents, GUI and messages etc.

• Impatient developers – can’t wait for Impatient developers – can’t wait for the design, need to start coding nowthe design, need to start coding now

Examples of designed user Examples of designed user assistanceassistance

• Conventional examples:Conventional examples:• Mouseover helpMouseover help• Inline pop-up help tips Inline pop-up help tips • Input field footnotes with links to more Input field footnotes with links to more

helphelp• Context-sensitive help setsContext-sensitive help sets

Two case studiesTwo case studies

1.1.Product whose focus and delivery Product whose focus and delivery has changed over the yearshas changed over the years

2.2.Product with a more normal product Product with a more normal product cycle and dedicated cross-functional cycle and dedicated cross-functional teamteam

Viv’s experienceViv’s experience

• No dedicated UXNo dedicated UX• Limited documentation resourcesLimited documentation resources• What can you do?What can you do?

– Already have a flexible teamAlready have a flexible team– Product requires quick turnaroundProduct requires quick turnaround– Content written before coding startsContent written before coding starts– Doc team contributes by validating, Doc team contributes by validating,

influencing, finding gapsinfluencing, finding gaps

Jim’s experienceJim’s experience

• More normal product cycleMore normal product cycle

• Dedicated user experience and Dedicated user experience and documentationdocumentation

• Early involvement in:Early involvement in:– Requirements gatheringRequirements gathering– Information architectureInformation architecture– Navigation & workflow designNavigation & workflow design

Information architectureInformation architecture

• Created by user experience engineer Created by user experience engineer for use by product designers, GUI for use by product designers, GUI designers and ID to structure content designers and ID to structure content design, page layout for wireframes design, page layout for wireframes and prototypesand prototypes

• Reference for final implementationReference for final implementation

GUI wireframeGUI wireframe

• Next step after Information architectureNext step after Information architecture• Low fidelity mockup of a page, with Low fidelity mockup of a page, with

behaviour, usage. workflow and behaviour, usage. workflow and interaction notesinteraction notes

• Writers use as basis for placing user Writers use as basis for placing user assistance in:assistance in:– Buttons, field labelsButtons, field labels– Dialog textDialog text– Page textPage text– Messages, etc.Messages, etc.

GUI prototypeGUI prototype

• Non functional high-fidelity mockup of Non functional high-fidelity mockup of pagespages

• More realistic interaction (buttons work, More realistic interaction (buttons work, links go someplace, help has text, links go someplace, help has text, mouseover text in place)mouseover text in place)

• Writer-provided user assistance Writer-provided user assistance information iin place - automatically information iin place - automatically flows into final UI (GUI developers share flows into final UI (GUI developers share code with GUI designers)code with GUI designers)

Demo implementationDemo implementation

• Actual GUI code in progress (e.g. the Actual GUI code in progress (e.g. the product state at end of first Sprint)product state at end of first Sprint)

• Most user assistance information in Most user assistance information in placeplace

• Most UI text already reviewed and Most UI text already reviewed and approvedapproved

Final thoughts …Final thoughts …

• Is this a valid goal for technical Is this a valid goal for technical communicators?communicators?

• Will this work for you? Can you start Will this work for you? Can you start designing instead of just designing instead of just documenting?documenting?

• Have traditional documentation goals Have traditional documentation goals changed in your world?changed in your world?

• How might social media help achieve How might social media help achieve new goals for user information?new goals for user information?

Key takeawaysKey takeaways

• Information Information designdesign enables transparent, enables transparent, comprehensive, and immediate comprehensive, and immediate end-user end-user assistanceassistance, not just writing manuals, not just writing manuals

• FirstFirst think about: think about:– Where Where and and whenwhen users need information users need information– How How to let users stay in their taskto let users stay in their task– HowHow the pieces you already know exist fit the pieces you already know exist fit

together to make a coherent together to make a coherent user user assistance system assistance system in the product in the product

• ThenThen think about think about whatwhat to write (if to write (if anything)anything)

Thank you!Thank you!

• Jim – jsmith@platform.com Jim – jsmith@platform.com

• Vivian – vaschwan@platform.comVivian – vaschwan@platform.com