Lavacon 2010: Stop Documenting and Start Designing - Smith & Aschwanden
Upcoming SlideShare
Loading in...5
×
 

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

on

  • 1,429 views

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.

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.

Statistics

Views

Total Views
1,429
Views on SlideShare
1,429
Embed Views
0

Actions

Likes
0
Downloads
21
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

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

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