Stop Documenting, Start Designing! How to get out of the traditional documentation box Jim Smith and Vivian Aschwanden Pla...
Session description  (from LavaCon program) <ul><li>A goal we should not forget as information developers/technical commun...
Where we will go today <ul><li>About us </li></ul><ul><li>Management context </li></ul><ul><li>Designing vs. documenting <...
Jim and Vivian <ul><li>Jim Smith </li></ul><ul><li>Technical Communicator, 20+ yrs, including — </li></ul><ul><ul><li>7 at...
What we do <ul><li>Information Development at Platform Computing: </li></ul><ul><ul><li>Plans, designs, writes, delivers u...
Platform Computing <ul><li>Platform Computing is the leader in cluster, grid and cloud management software with: </li></ul...
Spoiler alert – how the story ends <ul><li>First  think about: </li></ul><ul><ul><li>Where  and  when  users need informat...
Management context <ul><li>Strategic direction change for information development – move from command-line product to web ...
<ul><li>Photo:  stop  by  evaporated </li></ul>
How to stop documenting… <ul><li>Not stopping permanently, like driving up to a stop sign: we stop, look around, decide wh...
<ul><li>copyright ©2006 - 2009 by DesignForYourWine.com.® </li></ul>
And start designing … <ul><li>Be bold – put a stake in the ground and say no- I'm not documenting anything until the UX de...
What changes? <ul><li>Reviewing different kinds of design documents with a different focus </li></ul><ul><li>Starting to w...
What stays the same? <ul><li>Same raw materials: words on a page </li></ul><ul><li>Still review developer specifications a...
Design – what does it mean? <ul><li>Seamless   end-user assistance </li></ul><ul><li>Low impact  on user goals </li></ul><...
Design – how is it done? <ul><li>Enabled by cross-functional design team </li></ul><ul><li>Involvement at earliest point <...
Design – why do it? <ul><li>Designed information benefits  users : </li></ul><ul><ul><li>Supports “inadvertent learning” <...
Design – why do it? <ul><li>Designed information benefits  writers : </li></ul><ul><ul><li>Enables focus on the potential ...
Design – any obstacles? <ul><li>Making room on the screen for user assistance content </li></ul><ul><li>Writing reusable c...
Examples of designed user assistance <ul><li>Conventional examples: </li></ul><ul><ul><li>Mouseover help </li></ul></ul><u...
Two case studies <ul><li>Product whose focus and delivery has changed over the years </li></ul><ul><li>Product with a more...
Viv’s experience <ul><li>No dedicated UX </li></ul><ul><li>Limited documentation resources </li></ul><ul><li>What can you ...
Jim’s experience <ul><li>More normal product cycle </li></ul><ul><li>Dedicated user experience and documentation </li></ul...
Information architecture <ul><li>Created by user experience engineer for use by product designers, GUI designers and ID to...
GUI wireframe <ul><li>Next step after Information architecture </li></ul><ul><li>Low fidelity mockup of a page, with behav...
GUI prototype <ul><li>Non functional high-fidelity mockup of pages </li></ul><ul><li>More realistic interaction (buttons w...
Demo implementation <ul><li>Actual GUI code in progress (e.g. the product state at end of first Sprint) </li></ul><ul><li>...
Final thoughts … <ul><li>Is this a valid goal for technical communicators? </li></ul><ul><li>Will this work for you? Can y...
Key takeaways <ul><li>Information  design  enables transparent, comprehensive, and immediate  end-user assistance , not ju...
Thank you! <ul><li>Jim –  [email_address]   </li></ul><ul><li>Vivian –  [email_address]   </li></ul>
Upcoming SlideShare
Loading in …5
×

Lavacon 2010: Stop Documenting and Start Designing - Smith & Aschwanden

1,399 views

Published on

Presented at LavaCon 2010 in San Deigo: Learn how to stop “documenting a product” and start “designing information” so that needed information is presented to users where/when it’s needed.

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,399
On SlideShare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
25
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Lavacon 2010: Stop Documenting and Start Designing - Smith & Aschwanden

  1. 1. Stop Documenting, Start Designing! How to get out of the traditional documentation box Jim Smith and Vivian Aschwanden Platform Computing Corporation
  2. 2. Session description (from LavaCon program) <ul><li>A goal we should not forget as information developers/technical communicators (or whatever you want to call those who create documentation, literature, content for their company’s products) should be to design information. </li></ul><ul><li>Designing information, like designing software or a manufactured item or even a house, requires planning and time spent doing architectural design. We need to stop “documenting a product” and start “designing information” so that needed information is presented to users where/when it’s needed. </li></ul><ul><li>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 shift in our thinking, approach, and implementation of user information. </li></ul>
  3. 3. Where we will go today <ul><li>About us </li></ul><ul><li>Management context </li></ul><ul><li>Designing vs. documenting </li></ul><ul><ul><li>What changes, what doesn’t </li></ul></ul><ul><ul><li>What does it mean? How, why, obstacles </li></ul></ul><ul><li>Some examples </li></ul><ul><li>Our experiences </li></ul><ul><li>Final thoughts & takeaways </li></ul>
  4. 4. Jim and Vivian <ul><li>Jim Smith </li></ul><ul><li>Technical Communicator, 20+ yrs, including — </li></ul><ul><ul><li>7 at IBM </li></ul></ul><ul><ul><li>11 at Platform Computing </li></ul></ul><ul><ul><li>2 as Manager of ID/UX Team at Platform </li></ul></ul><ul><li>Starting PhD in Linguistics at University of Toronto </li></ul><ul><li>[email_address] </li></ul><ul><li>Vivian Aschwanden </li></ul><ul><li>Technical Communicator, 13 yrs, including — </li></ul><ul><ul><li>7 at Leitch/Harris Broadcasting; 3 as group leader </li></ul></ul><ul><ul><li>6 at Platform Computing </li></ul></ul><ul><li>Current roles: </li></ul><ul><ul><li>F/T senior ID </li></ul></ul><ul><ul><li>P/T program manager (CAPM) </li></ul></ul><ul><li>[email_address] </li></ul>
  5. 5. What we do <ul><li>Information Development at Platform Computing: </li></ul><ul><ul><li>Plans, designs, writes, delivers user documentation for all Platform software products </li></ul></ul><ul><ul><li>Participates fully in all phases of product development from initial product requirements, to user experience design, to packaging and delivery </li></ul></ul>
  6. 6. Platform Computing <ul><li>Platform Computing is the leader in cluster, grid and cloud management software with: </li></ul><ul><ul><li>2,000 customers in nearly every high performance computing environment </li></ul></ul><ul><ul><li>5 million CPUs under management </li></ul></ul><ul><ul><li>Strategic relationships with Cray, Dell, HP, IBM, Intel, Microsoft, Red Hat and SAS </li></ul></ul><ul><ul><li>530 professionals working across 10 global centers </li></ul></ul><ul><ul><li>More than 100 application partnerships for cluster, grid, and cloud enablement </li></ul></ul>
  7. 7. Spoiler alert – how the story ends <ul><li>First think about: </li></ul><ul><ul><li>Where and when users need information </li></ul></ul><ul><ul><li>How to let users stay in their task </li></ul></ul><ul><ul><li>How the pieces you already know exist fit together to make a coherent user assistance system in the product </li></ul></ul><ul><li>Then think about what to write (if anything) </li></ul>
  8. 8. Management context <ul><li>Strategic direction change for information development – move from command-line product to web application </li></ul><ul><li>New markets, new customers </li></ul><ul><li>Required new product and documentation strategies </li></ul><ul><li>Fewer team resources </li></ul><ul><li>Faster product release cycles </li></ul>
  9. 9. <ul><li>Photo: stop by evaporated </li></ul>
  10. 10. How to stop documenting… <ul><li>Not stopping permanently, like driving up to a stop sign: we stop, look around, decide which way to go then move ahead </li></ul><ul><li>For users to succeed, need to identify user information needs, and design to that </li></ul><ul><li>For new products to succeed need to do look at all aspects of development and design </li></ul><ul><li>Focus on entire user experience - put in processes and software tools/libraries/patterns to avoid hand crafting each page for each product </li></ul>
  11. 11. <ul><li>copyright ©2006 - 2009 by DesignForYourWine.com.® </li></ul>
  12. 12. And start designing … <ul><li>Be bold – put a stake in the ground and say no- I'm not documenting anything until the UX design is right </li></ul><ul><li>Resist the impulse to start documenting immediately – take the chance to get deeply involved in understanding workflow and information architecture </li></ul><ul><li>Gaps in the user interaction are a red flag to gaps in the design – push to fix the design rather than document around the gap </li></ul><ul><li>Get involved elsewhere in the building – if do find you need document, you already know where information should go and how much to write </li></ul>
  13. 13. What changes? <ul><li>Reviewing different kinds of design documents with a different focus </li></ul><ul><li>Starting to write conventional documentation as late as possible </li></ul><ul><li>Communicating with users more through the GUI than the documentation </li></ul><ul><li>Focusing effort on filling gaps in user interaction </li></ul>
  14. 14. What stays the same? <ul><li>Same raw materials: words on a page </li></ul><ul><li>Still review developer specifications and feature design documents, but not extracting feature/functionality info for user guides </li></ul><ul><li>Use design specifications for info to expose in the UI </li></ul>
  15. 15. Design – what does it mean? <ul><li>Seamless end-user assistance </li></ul><ul><li>Low impact on user goals </li></ul><ul><li>Immediate help – users not taken out of current task </li></ul><ul><li>Integrated transparently in GUI – users won’t even think of it as help </li></ul><ul><li>Minimal standalone documentation </li></ul><ul><li>Online help content searchable and context-sensitive </li></ul><ul><li>Does not eliminate need for conventional help </li></ul>
  16. 16. Design – how is it done? <ul><li>Enabled by cross-functional design team </li></ul><ul><li>Involvement at earliest point </li></ul><ul><li>Instead of describing features, we own all the words in the UI </li></ul><ul><li>Most content already exists in other product documentation – reuse in smaller help topics </li></ul><ul><li>Effort shifts to putting user assistance directly in the product UI </li></ul>
  17. 17. Design – why do it? <ul><li>Designed information benefits users : </li></ul><ul><ul><li>Supports “inadvertent learning” </li></ul></ul><ul><ul><li>Users are less aware they’re getting “help” – the entire UI becomes literally “helpful” </li></ul></ul><ul><ul><li>Encourages exploration </li></ul></ul><ul><ul><li>Increases customer success without being a time-wasting distraction </li></ul></ul>
  18. 18. Design – why do it? <ul><li>Designed information benefits writers : </li></ul><ul><ul><li>Enables focus on the potential user “pain points” </li></ul></ul><ul><ul><li>Less conventional procedural (“How do I?”) documentation </li></ul></ul><ul><ul><li>Integrated into GUI code as part of the UI </li></ul></ul><ul><ul><li>Designed at same time as overall user experience </li></ul></ul>
  19. 19. Design – any obstacles? <ul><li>Making room on the screen for user assistance content </li></ul><ul><li>Writing reusable content for documents, GUI and messages etc. </li></ul><ul><li>Impatient developers – can’t wait for the design, need to start coding now </li></ul>
  20. 20. Examples of designed user assistance <ul><li>Conventional examples: </li></ul><ul><ul><li>Mouseover help </li></ul></ul><ul><ul><li>Inline pop-up help tips </li></ul></ul><ul><ul><li>Input field footnotes with links to more help </li></ul></ul><ul><ul><li>Context-sensitive help sets </li></ul></ul>
  21. 21. Two case studies <ul><li>Product whose focus and delivery has changed over the years </li></ul><ul><li>Product with a more normal product cycle and dedicated cross-functional team </li></ul>
  22. 22. Viv’s experience <ul><li>No dedicated UX </li></ul><ul><li>Limited documentation resources </li></ul><ul><li>What can you do? </li></ul><ul><ul><li>Already have a flexible team </li></ul></ul><ul><ul><li>Product requires quick turnaround </li></ul></ul><ul><ul><li>Content written before coding starts </li></ul></ul><ul><ul><li>Doc team contributes by validating, influencing, finding gaps </li></ul></ul>
  23. 23. Jim’s experience <ul><li>More normal product cycle </li></ul><ul><li>Dedicated user experience and documentation </li></ul><ul><li>Early involvement in: </li></ul><ul><ul><li>Requirements gathering </li></ul></ul><ul><ul><li>Information architecture </li></ul></ul><ul><ul><li>Navigation & workflow design </li></ul></ul>
  24. 24. Information architecture <ul><li>Created by user experience engineer for use by product designers, GUI designers and ID to structure content design, page layout for wireframes and prototypes </li></ul><ul><li>Reference for final implementation </li></ul>
  25. 25. GUI wireframe <ul><li>Next step after Information architecture </li></ul><ul><li>Low fidelity mockup of a page, with behaviour, usage. workflow and interaction notes </li></ul><ul><li>Writers use as basis for placing user assistance in: </li></ul><ul><ul><li>Buttons, field labels </li></ul></ul><ul><ul><li>Dialog text </li></ul></ul><ul><ul><li>Page text </li></ul></ul><ul><ul><li>Messages, etc. </li></ul></ul>
  26. 26. GUI prototype <ul><li>Non functional high-fidelity mockup of pages </li></ul><ul><li>More realistic interaction (buttons work, links go someplace, help has text, mouseover text in place) </li></ul><ul><li>Writer-provided user assistance information iin place - automatically flows into final UI (GUI developers share code with GUI designers) </li></ul>
  27. 27. Demo implementation <ul><li>Actual GUI code in progress (e.g. the product state at end of first Sprint) </li></ul><ul><li>Most user assistance information in place </li></ul><ul><li>Most UI text already reviewed and approved </li></ul>
  28. 28. Final thoughts … <ul><li>Is this a valid goal for technical communicators? </li></ul><ul><li>Will this work for you? Can you start designing instead of just documenting? </li></ul><ul><li>Have traditional documentation goals changed in your world? </li></ul><ul><li>How might social media help achieve new goals for user information? </li></ul>
  29. 29. Key takeaways <ul><li>Information design enables transparent, comprehensive, and immediate end-user assistance , not just writing manuals </li></ul><ul><li>First think about: </li></ul><ul><ul><li>Where and when users need information </li></ul></ul><ul><ul><li>How to let users stay in their task </li></ul></ul><ul><ul><li>How the pieces you already know exist fit together to make a coherent user assistance system in the product </li></ul></ul><ul><li>Then think about what to write (if anything) </li></ul>
  30. 30. Thank you! <ul><li>Jim – [email_address] </li></ul><ul><li>Vivian – [email_address] </li></ul>

×