Avoiding Pitfalls When Single-Sourcing Print and Online

1. Avoiding Pitfalls When Single-Sourcing Print and Online Linda Urban WritersUA Conference 2006 Contact: lurban@earthlink.net www.urbancreations.com

2. About you • Already single-sourcing print and online? • Your experience • Encountering difficulties? • Pretty straightforward? • Your role • Primary information designer and developer • Part of a documentation team • Manager • Solution designer • Individual contributor/writer

3. About Linda • 20+ years as a technical communicator • Online help • Print/PDF documentation (user guides, admin guides, reference manuals) • Single-sourced solutions • Training materials (curriculum, handouts, workbooks) • Wear many hats, depending on project • Project manager Developmental editor • Designer Usability specialist • Writer Information architect • Teach in Technical Communication programs at UCB Extension, UCSC Extension

4. Defining single-sourcing for this talk • One set of information for multiple outputs (print and online) • “True” single-sourcing (you make adjustments to the source, not to the output) • Most of my recent experience is with WebWorks Publisher and FrameMaker • Ideas also applicable to tools that require more post-processing tweaks (such as RoboHelp & Word)

5. The Single-Sourcing Wish • Leverage the work you’ve already done • You have content written once, so reuse it • Push a button, get another output • With the right tool • A little bit of setup • Maybe a little bit more writing • Judicious use of conditionalized text • Click a button and out comes the alternate format. Voila!

6. The Reality • The good news Once set up, single-sourcing can work very well • But…getting there isn’t always easy • When most needed, most challenging • Complex projects, tight deadlines, stretched resources • Even when you’ve done single-sourcing before, you can wind up with surprises and headaches • This talk is aimed at minimizing the headaches and avoiding pitfalls

7. What we want • Quality, usable print and online information that provides what users need • Less stress, more efficiency, reduced costs • A workflow that makes sense to the team • Writers, editors, production • Reviewers • QA • Developers

8. Pitfalls to avoid Lots of them • Last minute reviewers who don’t like the results (printed docs, online help) • Writers who don’t understand the model • Unrealistic estimates or schedules • Disappointing output • Topics that are “lost in space” (no context) …. Most can be addressed by following guidelines

9. Guidelines for success • Involve and educate stakeholders • Create and demonstrate prototypes (print and online samples) • Don’t skimp when planning • Design a solution that works in your context • Provide adequate training and resources for writers • Adjust time and cost estimate to allow for single-sourcing • Test your solutions • Document design decisions, techniques, and process

10. 1. Involve and educate stakeholders • Your manager/primary client stakeholder • Project managers • Marketing • Reviewers • Development team • QA • And, of course, the documentation team: Writers, editors, production Talk to them early, keep them updated along the way, show them what you’re doing

11. You need their support If you don’t, you risk • Not enough money for resources • Unrealistic schedule • Writers who don’t understand the writing model • Results that are not what’s expected • Last minute requests for significant changes by reviewers • Errors in output

12. What’s involved?(In setting stakeholder expectations)

13. Set expectations for cost, process, deliverables • Short and long-range cost savings • 1st time: Less expensive than developing two sets of materials, but not “cheap” • Long-term: More substantial savings • Cost depends on ease or complexity of implementation and of content • Single sourcing is more than just converting to another output • Adjustments required to text AND to process

14. Stakeholders:Agree on goals for single-sourcing • Why do you want to single-source? • What are the objectives? • Provide another output? • Reduce costs? • Reuse information? • Improve quality (accuracy, consistency, usability)? • Is it OK for current deliverables to change?

15. Stakeholders:Agree on level of single-sourcing • What “level” of single-sourcing? • Convert print to an HTML-based book • Convert a subset of topics from printed document to become Help • Write modular topics that work for both print and online (This can range from “Vanilla” design to more elaborate design, improved usability.) • Provide context-sensitive help • These impact complexity of design… and therefore process • Also can impact print look & feel • Useful to look at examples

16. Example: Convert print to an HTML book • Simplest approach • Pages become topics • Cross-references become links • Next/Previous navigation • Assumption of linear use • Topics may not “stand alone” (no context-clues) • Works well for some content • Tutorials, such as Adobe/Macromedia’s Dreamweaver MX Getting Started Tutorial • Might be “first step” • Administrator guides for enterprise application

17. Example: Extract portion of User Guide as help • AMCC’s 3ware Serial ATA RAID Controller User Guide • Includes driver information, some hardware info • Task information covers two utilities: 3BM, 3DM • Online Help for 3DM is a subset of user guide • Main 3DM Intro and Reference • Most screenshots suppressed • Related Topics added to cross-reference tasks • System requirements and concepts • Only 3DM-related task information; not 3BM • Not same sequence as PDF • Some conditionalized headings required • Not yet context-sensitive

18. 1 Portions of the user guide belong in help 2 3

19. 2 But in the help, a different order is appropriate 1 3

20. Example: Modular topics that work for both print and online • Dreamweaver MX User Guide • Fairly simple approach • Topics have been modularized (they stand alone) • Some additional See Also cross-references added • Some linear references addressed (“pages” removed, but not “chapter”) • Reference sections in CHM, but not PDF • Some context-sensitive topics only in CHM, not linked into other topics (“Reference” sections throughout chm) • In some ways feels like print (long topics), in others like online help (stand-alone topics, Related Topics)

21. Stakeholders: Which output is most important—print or online? • When you have to make a trade-off, which way should you lean? • Lean to print • May have longer topics, less modular, optimized for reading, linear organization • Or may have highly designed pages • Lean to online – more modular (“chunkier”), less flow, optimized for reference • Are stakeholders in agreement?

22. Stakeholders:Understand requirements • Platforms (systems for HTML display) • Browsers Make sure your tools support the requirements • Example: Need Safari output? • Design requirements • Can you adjust existing look and feel?

23. Remember that reviewers are stakeholders • Educate reviewers about multiple outputs, get agreement for a review of each • Reviewers need to understand goals, so they review appropriately • Even though you prepare reviewers, they may not “get it” until they are reviewing • QA role also needed – someone to check for proper conditionalizing, tagging. Does print show for print, and online for online?

24. Stakeholders: Avoid surprises in print deliverables • People used to books (linear writing) may be put off by modular writing • Chapter/section intros that introduce a list of topics instead of focusing on concepts • Transitions (or the lack thereof) • Modular (“chunked”) writing style • Organization/integration of pieces • Placement and integration of cross-references • Prepare them. Show samples. Talk about benefits. If necessary, adjust design.

25. Stakeholders: Avoid surprises in online deliverables • Straight conversion from print • May have choppy topics • Some long • Some short • Topics may not “stand alone,” seem incomplete • Topics may lack context • Don’t leave testing until the end • Work out the kinks early • Determine minimum required changes

26. A Reference Topic in Print

27. Results from “straight conversion” where Headings 1, 2, and 3 are mapped to become new topics. Problem: gives the impression of being a complete topic, but is the first of 5 screens about it.

28. 2. Create and demonstrateprototypes: online and print • Work out kinks in design and implementation • Use actual content in the sample; make it robust enough to uncover issues • Communicate the approach to the writing team, and make sure it will work • Discover quirks of tools and the resulting outputs, and resolve issues

29. How complete must this be? • As robust as possible, using real content • If you don’t, you risk • Uncovering problems late in the game • Creating documents and help that are different from what people expect • Creating a design writers don’t follow

30. Show your solutions • Put users in front of your prototype • Confirm your decisions for both print and online • Put stakeholders in front of your prototype • Surface concerns or desired changes and reach agreement • Avoid surprises! • Review all outputs

31. 3. Don’t Skimp When Planning • Allow plenty of planning time • Even if you’ve done single-sourcing for this product • Even if you know your group or client well • Put your decisions into a written plan • Working document is fine • Update it as it evolves

32. Planning helps you think things all the way through If you don’t, you risk • Designing something that doesn’t meet user needs • Underestimating work that must be done (Who knew there were THAT many overrides in the files?) • Forgetting to ask for process changes • Include a QA pass • Reviewers look at both print and online • Keeping design decisions in your brain instead of telling people about them • Getting approval for your plan

33. Planning:Know your audience • Consider their needs • Printed documentation • Online help or documentation • When will they use each? • What will their experience be like with each? • Plan to user-test your prototype

34. Planning:Do a content analysis • Define what topics need to be created • Detail what information exists • Assess it’s state • Determine what updates are required • Match it to information design/topic design • Create a content inventory

35. Planning:Create a content inventory • New material • Create an annotated outline • Make notes about print and online needs • Existing material: analyze what’s there • Print • Online • Required areas for change • A preliminary conversion can help

36. Planning:Identify problematic files • Be ruthless about changes needed for consistency, appropriate use of template

37. 4. Design a solution that works in your context • Design for your information and goals • Don’t forget the big picture • Complexity of information • State of the project Where on the continuum is it, from • Clear, well-defined, reasonable schedule To • Chaotic, changing requirements, shifting information, rush job

38. Create an appropriate design If you don’t, you risk • Developing a sophisticated design when a simple one is called for • Creating a design that can’t be implemented because the writers don’t have time • Disappointing output • Poor usability • Stressed writers • Unhappy stakeholders

39. Define (and design) topic types • Identify topic types, detail their patterns • Task • Reference • Concept • Example • Others…

40. Flesh out samples of topic patterns • Provide models for writers from the first draft forward • Create real sample topics, with project content • Explain them • Add them to your style guide

41. How will you customize your content? Try this: • Write a section for print • Write the same section for online • Compare: What are the differences? • Try converting in each direction • From print to online • From online to print • What are the gains/losses each way? • Adapt • Can a change meet both needs? • Should you add conditional text for one or the other?

42. Decide how to get from one output to the other For example: • Where topic splits occur (from printed docs) • What is bookmarked (links down the page) • Will you use drop-down text • Does all information belong in each output • What is conditionalized • What new text is required for each output • Will you reorganize information • What will be the file structure • How to handle cross-references and related topics

43. One Example Moving a long reference section from print to online

44. 1st Step: Straight conversion, mapping Heading 1 and 2 to become topics, hiding images Result: long topic

45. Consider options for improvement

46. Consider options for improvement 1. Add a list of sections Cross-references become links to headings down the page Also provide links in PDF Still kind of long…

47. Consider options for improvement 2. Chunk further Sub-headings become new topics (H1, H2, H3) New topics lose context To be effective, need Related topics or See Also’s Decision: would that be only for online, or also print?

48. Consider options for improvement 3. Expanding headings Scannable and flexible Won’t show in print Index issues

49. Design decisions:Handling context-sensitive help • What needs it? • Screens or windows • Dialog boxes • Palettes • Toolbars

50. What topics will be context-sensitive? From the online perspective, there are plenty of questions… What topic should display first? • Overview (access to all info) • Task (if one is primary) • Reference (ex: dialog box) • Other…