11
Avoiding Pitfalls When Single-Avoiding Pitfalls When Single-Sourcing Print and OnlineSourcing Print and Online
Linda UrbanLinda UrbanWritersUA Conference 2006WritersUA Conference 2006Contact: Contact: [email protected]@earthlink.net
www.urbancreations.comwww.urbancreations.com
© 2006 Linda Urban 2
About youAbout you
►Already single-sourcing print and Already single-sourcing print and online?online?
►Your experienceYour experience Encountering difficulties?Encountering difficulties? Pretty straightforward?Pretty straightforward?
►Your roleYour role Primary information designer and developerPrimary information designer and developer Part of a documentation teamPart of a documentation team
►ManagerManager►Solution designerSolution designer►Individual contributor/writerIndividual contributor/writer
© 2006 Linda Urban 3
About LindaAbout Linda
► 20+ years as a technical communicator 20+ years as a technical communicator Online helpOnline help Print/PDF documentation (user guides, admin guides, Print/PDF documentation (user guides, admin guides,
reference manuals) reference manuals) Single-sourced solutionsSingle-sourced solutions Training materials (curriculum, handouts, workbooks)Training materials (curriculum, handouts, workbooks)
► Wear many hats, depending on projectWear many hats, depending on project Project managerProject manager Developmental editorDevelopmental editor Designer Designer Usability specialistUsability specialist WriterWriter Information architectInformation architect
► Teach in Technical Communication programs at Teach in Technical Communication programs at UCB Extension, UCSC ExtensionUCB Extension, UCSC Extension
© 2006 Linda Urban 4
Defining single-sourcing Defining single-sourcing for this talkfor this talk► One set of information for multiple outputs One set of information for multiple outputs
(print and online)(print and online)
► ““True” single-sourcing (you make True” single-sourcing (you make adjustments to the source, not to the adjustments to the source, not to the output)output)
► Most of my recent experience is with Most of my recent experience is with WebWorks Publisher and FrameMakerWebWorks Publisher and FrameMaker
► Ideas also applicable to tools that require Ideas also applicable to tools that require more post-processing tweaks (such as more post-processing tweaks (such as RoboHelp & Word)RoboHelp & Word)
© 2006 Linda Urban 5
The Single-Sourcing WishThe Single-Sourcing Wish
►Leverage the work you’ve already doneLeverage the work you’ve already done You have content written once, so reuse itYou have content written once, so reuse it
►Push a button, get another outputPush a button, get another output With the right tool With the right tool A little bit of setupA little bit of setup Maybe a little bit more writingMaybe a little bit more writing Judicious use of conditionalized textJudicious use of conditionalized text Click a button and out comes the alternate Click a button and out comes the alternate
format. Voila!format. Voila!
© 2006 Linda Urban 6
The RealityThe Reality
► The good newsThe good newsOnce set up, single-sourcing can work very Once set up, single-sourcing can work very
wellwell► But…getting there isn’t always easyBut…getting there isn’t always easy
When most needed, most challengingWhen most needed, most challenging Complex projects, tight deadlines, stretched Complex projects, tight deadlines, stretched
resourcesresources
► Even when you’ve done single-sourcing before, Even when you’ve done single-sourcing before, you can wind up with surprises and headachesyou can wind up with surprises and headaches
► This talk is aimed at minimizing the headaches This talk is aimed at minimizing the headaches and avoiding pitfallsand avoiding pitfalls
© 2006 Linda Urban 7
What we wantWhat we want
►Quality, usable print and online information Quality, usable print and online information that provides what users needthat provides what users need
►Less stress, more efficiency, reduced costsLess stress, more efficiency, reduced costs►A workflow that makes sense to the teamA workflow that makes sense to the team
Writers, editors, productionWriters, editors, production ReviewersReviewers QAQA DevelopersDevelopers
© 2006 Linda Urban 8
Pitfalls to avoidPitfalls to avoid
Lots of themLots of them►Last minute reviewers who don’t like the Last minute reviewers who don’t like the
results (printed docs, online help)results (printed docs, online help)►Writers who don’t understand the modelWriters who don’t understand the model►Unrealistic estimates or schedulesUnrealistic estimates or schedules►Disappointing outputDisappointing output►Topics that are “lost in space” (no context)Topics that are “lost in space” (no context)
……..
Most can be addressed by following Most can be addressed by following guidelinesguidelines
© 2006 Linda Urban 9
Guidelines for successGuidelines for success
1.1. Involve and educate stakeholdersInvolve and educate stakeholders2.2. Create and demonstrate prototypes (print and Create and demonstrate prototypes (print and
online samples)online samples)3.3. Don’t skimp when planningDon’t skimp when planning4.4. Design a solution that works Design a solution that works in your contextin your context5.5. Provide adequate training and resources for Provide adequate training and resources for
writerswriters6.6. Adjust time and cost estimate to allow for single-Adjust time and cost estimate to allow for single-
sourcingsourcing7.7. Test your solutionsTest your solutions8.8. Document design decisions, techniques, and Document design decisions, techniques, and
processprocess
© 2006 Linda Urban 10
1. Involve and educate 1. Involve and educate stakeholdersstakeholders► Your manager/primary client stakeholderYour manager/primary client stakeholder► Project managersProject managers► MarketingMarketing► ReviewersReviewers► Development teamDevelopment team► QAQA► And, of course, the documentation team: And, of course, the documentation team:
Writers, editors, productionWriters, editors, production
Talk to them early, keep them updated Talk to them early, keep them updated along the way, show them what you’re doingalong the way, show them what you’re doing
© 2006 Linda Urban 11
You need their supportYou need their support
If you don’t, you riskIf you don’t, you risk►Not enough money for resourcesNot enough money for resources►Unrealistic scheduleUnrealistic schedule►Writers who don’t understand the Writers who don’t understand the
writing modelwriting model►Results that are not what’s expectedResults that are not what’s expected►Last minute requests for significant Last minute requests for significant
changes by reviewerschanges by reviewers►Errors in outputErrors in output
1212
What’s involved?What’s involved?(In setting stakeholder (In setting stakeholder
expectations)expectations)
© 2006 Linda Urban 13
Set expectations for cost, Set expectations for cost, process, deliverablesprocess, deliverables►Short and long-range cost savingsShort and long-range cost savings
1st time: Less expensive than developing 1st time: Less expensive than developing two sets of materials, but not “cheap”two sets of materials, but not “cheap”
Long-term: More substantial savingsLong-term: More substantial savings
►Cost depends on ease or complexity of Cost depends on ease or complexity of implementation and of contentimplementation and of content
►Single sourcing is more than just Single sourcing is more than just converting to another outputconverting to another output Adjustments required to text AND to Adjustments required to text AND to
processprocess
© 2006 Linda Urban 14
Stakeholders:Stakeholders:Agree on goals for single-Agree on goals for single-sourcingsourcing►Why do you want to single-source? Why do you want to single-source? ►What are the objectives?What are the objectives?
Provide another output?Provide another output?
Reduce costs?Reduce costs?
Reuse information?Reuse information?
Improve quality (accuracy, consistency, Improve quality (accuracy, consistency, usability)?usability)?
► Is it OK for current deliverables to Is it OK for current deliverables to change?change?
© 2006 Linda Urban 15
Stakeholders:Stakeholders:Agree on level of single-Agree on level of single-sourcingsourcing► What “level” of single-sourcing?What “level” of single-sourcing?
Convert print to an HTML-based bookConvert print to an HTML-based book Convert a subset of topics from printed document to Convert a subset of topics from printed document to
become Helpbecome Help Write modular topics that work for both print and Write modular topics that work for both print and
onlineonline
(This can range from “Vanilla” design to more (This can range from “Vanilla” design to more elaborate design, improved usability.)elaborate design, improved usability.)
Provide context-sensitive helpProvide context-sensitive help► These impact complexity of design… and therefore These impact complexity of design… and therefore
processprocess► Also can impact print look & feelAlso can impact print look & feel► Useful to look at examplesUseful to look at examples
© 2006 Linda Urban 16
Example: Example: Convert print to an HTML bookConvert print to an HTML book►Simplest approachSimplest approach
Pages become topicsPages become topics Cross-references become linksCross-references become links Next/Previous navigationNext/Previous navigation Assumption of linear useAssumption of linear use Topics may not “stand alone” (no context-clues)Topics may not “stand alone” (no context-clues)
►Works well for some contentWorks well for some content Tutorials, such as Adobe/Macromedia’s Tutorials, such as Adobe/Macromedia’s
Dreamweaver MX Getting Started TutorialDreamweaver MX Getting Started Tutorial
►Might be “first step”Might be “first step” Administrator guides for enterprise applicationAdministrator guides for enterprise application
© 2006 Linda Urban 17
Example: Example: Extract portion of User Guide as Extract portion of User Guide as helphelp► AMCC’s AMCC’s 3ware Serial ATA RAID Controller 3ware Serial ATA RAID Controller
User GuideUser Guide Includes driver information, some hardware infoIncludes driver information, some hardware info Task information covers two utilities: 3BM, 3DMTask information covers two utilities: 3BM, 3DM
► Online Help for 3DM is a subset of user guideOnline Help for 3DM is a subset of user guide Main 3DM Intro and ReferenceMain 3DM Intro and Reference
► Most screenshots suppressedMost screenshots suppressed► Related Topics added to cross-reference tasksRelated Topics added to cross-reference tasks
System requirements and conceptsSystem requirements and concepts Only 3DM-related task information; not 3BMOnly 3DM-related task information; not 3BM Not same sequence as PDFNot same sequence as PDF Some conditionalized headings requiredSome conditionalized headings required Not yet context-sensitiveNot yet context-sensitive
© 2006 Linda Urban 18
11
22
33
Portions of the Portions of the user guide user guide belong in helpbelong in help
© 2006 Linda Urban 19
22
11
33
But in the help, But in the help, a different a different order is order is appropriateappropriate
© 2006 Linda Urban 20
Example: MoExample: Modular topics that dular topics that work for both print and onlinework for both print and online► Dreamweaver MX User GuideDreamweaver MX User Guide
Fairly simple approachFairly simple approach Topics have been modularized (they stand alone)Topics have been modularized (they stand alone) Some additional See Also cross-references addedSome additional See Also cross-references added Some linear references addressed (“pages” Some linear references addressed (“pages”
removed, but not “chapter”)removed, but not “chapter”) Reference sections in CHM, but not PDFReference sections in CHM, but not PDF Some context-sensitive topics only in CHM, not Some context-sensitive topics only in CHM, not
linked into other topics (“Reference” sections linked into other topics (“Reference” sections throughout chm)throughout chm)
► In some ways feels like print (long topics), in In some ways feels like print (long topics), in others like online help (stand-alone topics, others like online help (stand-alone topics, Related Topics)Related Topics)
© 2006 Linda Urban 21
Stakeholders: Which output is Stakeholders: Which output is most important—print or most important—print or online?online? ►When you have to make a trade-off, When you have to make a trade-off,
which way should you lean?which way should you lean? Lean to printLean to print
►May have longer topics, less modular, May have longer topics, less modular, optimized for reading, linear organizationoptimized for reading, linear organization
►Or may have highly designed pagesOr may have highly designed pages Lean to online – more modular (“chunkier”), Lean to online – more modular (“chunkier”),
less flow, optimized for referenceless flow, optimized for reference
►Are stakeholders in agreement?Are stakeholders in agreement?
© 2006 Linda Urban 22
Stakeholders:Stakeholders:Understand requirementsUnderstand requirements►Platforms (systems for HTML display)Platforms (systems for HTML display)►Browsers Browsers
Make sure your tools support the Make sure your tools support the requirementsrequirements Example: Need Safari output?Example: Need Safari output?
►Design requirementsDesign requirements Can you adjust existing look and feel?Can you adjust existing look and feel?
© 2006 Linda Urban 23
Remember that reviewers are Remember that reviewers are stakeholdersstakeholders►Educate reviewers about multiple outputs, Educate reviewers about multiple outputs,
get agreement for a review of eachget agreement for a review of each►Reviewers need to understand goals, so Reviewers need to understand goals, so
they review appropriatelythey review appropriately►Even though you prepare reviewers, they Even though you prepare reviewers, they
may not “get it” until they are reviewingmay not “get it” until they are reviewing►QA role also needed – someone to check QA role also needed – someone to check
for proper conditionalizing, tagging. Does for proper conditionalizing, tagging. Does print show for print, and online for online?print show for print, and online for online?
© 2006 Linda Urban 24
Stakeholders: Stakeholders: Avoid surprises in print Avoid surprises in print deliverablesdeliverables► People used to books (linear writing) may be People used to books (linear writing) may be
put off by modular writingput off by modular writing Chapter/section intros that introduce a list of Chapter/section intros that introduce a list of
topics instead of focusing on conceptstopics instead of focusing on concepts Transitions (or the lack thereof)Transitions (or the lack thereof) Modular (“chunked”) writing styleModular (“chunked”) writing style Organization/integration of piecesOrganization/integration of pieces Placement and integration of cross-referencesPlacement and integration of cross-references
► Prepare them. Show samples. Talk about Prepare them. Show samples. Talk about benefits. If necessary, adjust design.benefits. If necessary, adjust design.
© 2006 Linda Urban 25
Stakeholders: Stakeholders: Avoid surprises in online Avoid surprises in online deliverablesdeliverables►Straight conversion from printStraight conversion from print
May have choppy topicsMay have choppy topics►Some longSome long►Some shortSome short
Topics may not “stand alone,” seem Topics may not “stand alone,” seem incompleteincomplete
Topics may lack context Topics may lack context
►Don’t leave testing until the endDon’t leave testing until the end►Work out the kinks earlyWork out the kinks early►Determine minimum required changesDetermine minimum required changes
© 2006 Linda Urban 26
A Reference A Reference Topic in PrintTopic in Print
© 2006 Linda Urban 27
Results from Results from “straight “straight conversion” conversion” where where Headings 1, 2, Headings 1, 2, and 3 are and 3 are mapped to mapped to become new become new topics. topics.
Problem: Problem: gives the gives the impression of impression of being a being a complete complete topic, but is topic, but is the first of 5 the first of 5 screens about screens about it.it.
© 2006 Linda Urban 28
2. Create and demonstrate2. Create and demonstrateprototypes: online and printprototypes: online and print►Work out kinks in design and Work out kinks in design and
implementationimplementation►Use actual content in the sample; make it Use actual content in the sample; make it
robust enough to uncover issuesrobust enough to uncover issues►Communicate the approach to the writing Communicate the approach to the writing
team, and make sure it will workteam, and make sure it will work►Discover quirks of tools and the resulting Discover quirks of tools and the resulting
outputs, and resolve issuesoutputs, and resolve issues
© 2006 Linda Urban 29
How complete must this be?How complete must this be?
►As robust as possible, using real As robust as possible, using real contentcontent
► If you don’t, you riskIf you don’t, you risk Uncovering problems late in the gameUncovering problems late in the game Creating documents and help that are Creating documents and help that are
different from what people expectdifferent from what people expect Creating a design writers don’t followCreating a design writers don’t follow
© 2006 Linda Urban 30
Show your solutionsShow your solutions
►Put users in front of your prototypePut users in front of your prototype Confirm your decisions for both print and Confirm your decisions for both print and
onlineonline
►Put stakeholders in front of your Put stakeholders in front of your prototypeprototype Surface concerns or desired changes and Surface concerns or desired changes and
reach agreementreach agreement Avoid surprises!Avoid surprises!
►Review all outputsReview all outputs
© 2006 Linda Urban 31
3. Don’t Skimp When Planning3. Don’t Skimp When Planning
►Allow plenty of planning timeAllow plenty of planning time Even if you’ve done single-sourcing for Even if you’ve done single-sourcing for
this product this product
Even if you know your group or client well Even if you know your group or client well
►Put your decisions into a written plan Put your decisions into a written plan Working document is fineWorking document is fine
Update it as it evolvesUpdate it as it evolves
© 2006 Linda Urban 32
Planning helps you think Planning helps you think things all the way throughthings all the way throughIf you don’t, you riskIf you don’t, you risk► Designing something that doesn’t meet user Designing something that doesn’t meet user
needsneeds► Underestimating work that must be doneUnderestimating work that must be done
(Who knew there were THAT many overrides (Who knew there were THAT many overrides in the files?)in the files?)
► Forgetting to ask for process changesForgetting to ask for process changes Include a QA passInclude a QA pass Reviewers look at both print and onlineReviewers look at both print and online
► Keeping design decisions in your brain Keeping design decisions in your brain instead of telling people about theminstead of telling people about them
► Getting approval for your planGetting approval for your plan
© 2006 Linda Urban 33
Planning:Planning:Know your audienceKnow your audience►Consider their needsConsider their needs
Printed documentationPrinted documentation Online help or documentationOnline help or documentation
►When will they use each?When will they use each?►What will their experience be like with What will their experience be like with
each?each?
►Plan to user-test your prototypePlan to user-test your prototype
© 2006 Linda Urban 34
Planning:Planning:Do a content analysisDo a content analysis►Define what topics need to be Define what topics need to be
createdcreated►Detail what information exists Detail what information exists
Assess it’s stateAssess it’s state Determine what updates are requiredDetermine what updates are required
►Match it to information design/topic Match it to information design/topic designdesign
►Create a content inventoryCreate a content inventory
© 2006 Linda Urban 35
Planning:Planning:Create a content inventoryCreate a content inventory►New materialNew material
Create an annotated outlineCreate an annotated outline Make notes about print and online needsMake notes about print and online needs
►Existing material: analyze what’s Existing material: analyze what’s therethere PrintPrint OnlineOnline Required areas for changeRequired areas for change A preliminary conversion can helpA preliminary conversion can help
© 2006 Linda Urban 36
Planning:Planning:Identify problematic filesIdentify problematic files►Be ruthless about changes needed for Be ruthless about changes needed for
consistency, appropriate use of consistency, appropriate use of templatetemplate
© 2006 Linda Urban 37
4. Design a solution that 4. Design a solution that works in your contextworks in your context►Design for your information and Design for your information and
goalsgoals►Don’t forget the big pictureDon’t forget the big picture
Complexity of informationComplexity of information State of the projectState of the project
Where on the continuum is it, from Where on the continuum is it, from ►Clear, well-defined, reasonable scheduleClear, well-defined, reasonable scheduleToTo►Chaotic, changing requirements, shifting Chaotic, changing requirements, shifting
information, rush jobinformation, rush job
© 2006 Linda Urban 38
Create an appropriate designCreate an appropriate design
If you don’t, you riskIf you don’t, you risk►Developing a sophisticated design when Developing a sophisticated design when
a simple one is called fora simple one is called for►Creating a design that can’t be Creating a design that can’t be
implemented because the writers don’t implemented because the writers don’t have timehave time
►Disappointing outputDisappointing output►Poor usabilityPoor usability►Stressed writersStressed writers►Unhappy stakeholdersUnhappy stakeholders
© 2006 Linda Urban 39
Define (and design) topic Define (and design) topic typestypes► Identify topic types, detail their Identify topic types, detail their
patternspatterns TaskTask
ReferenceReference
ConceptConcept
ExampleExample
Others…Others…
© 2006 Linda Urban 40
Flesh out samples of topic Flesh out samples of topic patternspatterns►Provide models for writers from the Provide models for writers from the
first draft forwardfirst draft forward►Create real sample topics, with project Create real sample topics, with project
contentcontent
►Explain themExplain them►Add them to your style guideAdd them to your style guide
© 2006 Linda Urban 41
How will you customize your How will you customize your content?content?Try this:Try this:► Write a section for printWrite a section for print► Write the same section for onlineWrite the same section for online► Compare: What are the differences?Compare: What are the differences?► Try converting in each directionTry converting in each direction
From print to onlineFrom print to online From online to printFrom online to print What are the gains/losses each way?What are the gains/losses each way?
► AdaptAdapt Can a change meet both needs?Can a change meet both needs? Should you add conditional text for one or the Should you add conditional text for one or the
other?other?
© 2006 Linda Urban 42
Decide how to get from one Decide how to get from one output to the otheroutput to the otherFor example:For example:► Where topic splits occur (from printed docs)Where topic splits occur (from printed docs)► What is bookmarked (links down the page)What is bookmarked (links down the page)► Will you use drop-down textWill you use drop-down text► Does all information belong in each outputDoes all information belong in each output► What is conditionalizedWhat is conditionalized► What new text is required for each outputWhat new text is required for each output► Will you reorganize informationWill you reorganize information► What will be the file structureWhat will be the file structure► How to handle cross-references and related How to handle cross-references and related
topics topics
© 2006 Linda Urban 43
Moving a long Moving a long reference reference section from section from print to onlineprint to online
One ExampleOne Example
© 2006 Linda Urban 44
11stst Step: Step: Straight conversion, Straight conversion, mapping Heading 1 mapping Heading 1 and 2 to become and 2 to become topics, hiding imagestopics, hiding images
Result: long topicResult: long topic
© 2006 Linda Urban 45
Consider options Consider options for for improvementimprovement
© 2006 Linda Urban 46
Consider options Consider options for for improvementimprovement
1. Add a list of 1. Add a list of sectionssections
Cross-Cross-references references become links become links to headings to headings down the down the pagepage
Also provide Also provide links in PDFlinks in PDF
Still kind of Still kind of long…long…
© 2006 Linda Urban 47
Consider options Consider options for for improvementimprovement
2. Chunk 2. Chunk furtherfurther
Sub-headings Sub-headings become new become new topics (H1, H2, topics (H1, H2, H3)H3)
New topics lose New topics lose contextcontext
To be effective, To be effective, need Related need Related topics or See topics or See Also’s Also’s
Decision: would Decision: would that be only for that be only for online, or also online, or also print?print?
© 2006 Linda Urban 48
Consider options Consider options for for improvementimprovement
3. Expanding 3. Expanding headings headings
Scannable Scannable and flexibleand flexibleWon’t show in Won’t show in print Index issues print Index issues
© 2006 Linda Urban 49
Design decisions:Design decisions:Handling context-sensitive Handling context-sensitive helphelp►What needs it?What needs it?
Screens or windowsScreens or windows Dialog boxesDialog boxes PalettesPalettes Toolbars Toolbars
© 2006 Linda Urban 50
What topics will be context-What topics will be context-sensitive?sensitive?From the online perspective, there are From the online perspective, there are
plenty of questions…plenty of questions…
What topic should display first?What topic should display first?►Overview (access to all info)Overview (access to all info)►Task (if one is primary)Task (if one is primary)►Reference (ex: dialog box)Reference (ex: dialog box)►Other…Other…
© 2006 Linda Urban 51
From the print perspective…From the print perspective…
►Do appropriate context-sensitive Do appropriate context-sensitive topics already exist?topics already exist?
► If they need to be created, will they go If they need to be created, will they go in the printed doc?in the printed doc?
► If so, where? If so, where? OK to intersperse?OK to intersperse? Separate chapter?Separate chapter? Impact on file chunking and organization?Impact on file chunking and organization?
© 2006 Linda Urban 52
An example An example from from QuickenQuicken
© 2006 Linda Urban 53
Design decisions:Design decisions:Consider impacts of special Consider impacts of special effectseffects►Try them out, identify issues, writer Try them out, identify issues, writer
taskstasks►Example: expanding/contracting textExample: expanding/contracting text
Writers have to know what methods make Writers have to know what methods make sections become “expandable”sections become “expandable”
Can require unexpected organization of Can require unexpected organization of chunks within topicschunks within topics
►Other design elements may raise Other design elements may raise similar issues (Example: popups)similar issues (Example: popups)
© 2006 Linda Urban 54
Image is Image is available in available in online help, but online help, but hidden at firsthidden at first
Field table “drop-Field table “drop-down” is down” is expanded, so expanded, so items can be items can be indexed; requires indexed; requires a different taga different tag
This pattern This pattern using using expanding expanding sections is sections is somewhat somewhat complex, complex, although on although on the surface it the surface it may not look may not look it. it.
© 2006 Linda Urban 55
PDF page of PDF page of the expanding the expanding exampleexample
© 2006 Linda Urban 56
This pattern This pattern using using expanding expanding sections is sections is straight-straight-forwardforward
© 2006 Linda Urban 57
PDF page of PDF page of the expanding the expanding exampleexample
© 2006 Linda Urban 58
Design decisions:Design decisions:Work with the writersWork with the writers► Design a solution that makes senseDesign a solution that makes sense► When content is complex, writers focus on the When content is complex, writers focus on the
content (as they should)content (as they should)► Single-sourcing solutions add complexity of their ownSingle-sourcing solutions add complexity of their own► Allow time for a single-sourcing pass Allow time for a single-sourcing pass ► It’s easy to make mistakes It’s easy to make mistakes
ConditionalizingConditionalizing Catching linear references (below/above, numbering of Catching linear references (below/above, numbering of
figures, etc)figures, etc) Adapting cross-referencesAdapting cross-references Providing appropriate links/navigationProviding appropriate links/navigation
► The safety net of editors, reviewers, and QA The safety net of editors, reviewers, and QA becomes more importantbecomes more important
© 2006 Linda Urban 59
5. Provide adequate training 5. Provide adequate training and resources for writersand resources for writers► Whether the team is you, or a dozen writersWhether the team is you, or a dozen writers
► Writing for online is an acquired skillWriting for online is an acquired skill
► Writing for both print and online is another Writing for both print and online is another acquired skillacquired skill
► Getting used to a new pattern also takes time Getting used to a new pattern also takes time for experienced single-sourcersfor experienced single-sourcers
► Allow time for learning, and getting up to Allow time for learning, and getting up to speedspeed
► Especially true for writers new to single-Especially true for writers new to single-sourcingsourcing
© 2006 Linda Urban 60
Provide trainingProvide training
► If you don’t, you riskIf you don’t, you risk Needing extra time for revisionsNeeding extra time for revisions Frustrated writersFrustrated writers Frustrated production staffFrustrated production staff Impacting the scheduleImpacting the schedule Print or online output that doesn’t quite Print or online output that doesn’t quite
workwork Lower qualityLower quality
© 2006 Linda Urban 61
““Writer education” isn’t just Writer education” isn’t just up front trainingup front training► Writers need resourcesWriters need resources► Develop a style guideDevelop a style guide► Include lots of examplesInclude lots of examples► Create IA-like deliverables (wireframes, content Create IA-like deliverables (wireframes, content
inventory)inventory)► Have a working prototypeHave a working prototype► Have developmental edits that show, discuss Have developmental edits that show, discuss ► Include/consider training in the schedule Include/consider training in the schedule
It’s not just the additional hours – it’s when they occurIt’s not just the additional hours – it’s when they occur
► Writers need a way to see all outputs (workflows Writers need a way to see all outputs (workflows don’t always allow for that)don’t always allow for that)
© 2006 Linda Urban 63
Have some resource slackHave some resource slack
► Slack might includeSlack might include More hoursMore hours More editing assistanceMore editing assistance Another writerAnother writer Schedule that isn’t completely maxed outSchedule that isn’t completely maxed out
► Even though you prepare writers, some may Even though you prepare writers, some may find it harder than they expectedfind it harder than they expected
► Especially when Especially when Subject matter is complexSubject matter is complex Design is complexDesign is complex
© 2006 Linda Urban 64
6. Adjust time and cost 6. Adjust time and cost estimates for single- sourcingestimates for single- sourcing► It’s not enough to add time forIt’s not enough to add time for
Creating the output template or processCreating the output template or process Conversion time at the endConversion time at the end
► It’s easy to underestimate time for It’s easy to underestimate time for prototypingprototyping Not just a time & $ factor…needs to be in Not just a time & $ factor…needs to be in
place for other peopleplace for other people
© 2006 Linda Urban 65
Adjust time and cost Adjust time and cost estimates estimates If you don’t, you riskIf you don’t, you risk►Underestimating costs and time Underestimating costs and time
requiredrequired►Missing schedulesMissing schedules► Increased stressIncreased stress►Lowered quality Lowered quality
© 2006 Linda Urban 66
Include time for new tasksInclude time for new tasks
► Designing the solutionDesigning the solution
► Creating prototypes (online and print)Creating prototypes (online and print)
► Creating a style guide that includes plenty Creating a style guide that includes plenty of examplesof examples
► Training--in the process and the designTraining--in the process and the design WritersWriters EditorsEditors ReviewersReviewers
► Tool “tweaks and trouble-shooting”Tool “tweaks and trouble-shooting”
© 2006 Linda Urban 67
Re-evaluate time for known Re-evaluate time for known taskstasks► Think through each part of your processThink through each part of your process► Include extra time forInclude extra time for
Communication (meetings) Communication (meetings) ► With stakeholdersWith stakeholders► Between writing team Between writing team
WritingWriting► Writers need to consider each outputWriters need to consider each output► Writers may need to adjust their styleWriters may need to adjust their style► Clean-up of existing material required to work both waysClean-up of existing material required to work both ways
EditingEditing► More developmental editingMore developmental editing► More substantive and copy editingMore substantive and copy editing
► Reviewing of each output, as well as primary Reviewing of each output, as well as primary content reviewcontent review
► Production (multiple outputs, multiple times)Production (multiple outputs, multiple times)
© 2006 Linda Urban 68
How much extra time?How much extra time?
Depends onDepends on► Complexity of designs Complexity of designs
How different are print and online?How different are print and online? How many special effects?How many special effects? Context-sensitivity?Context-sensitivity?
► Complexity of materialComplexity of material► When users are hard at work understanding and When users are hard at work understanding and
writing, modularity may come in a 2nd passwriting, modularity may come in a 2nd pass► Size of writing teamSize of writing team► Writers’ experience with modular writingWriters’ experience with modular writing► Writers’ experience with conditionalizing for Writers’ experience with conditionalizing for
different outputsdifferent outputs► Track your metrics, so you know for the futureTrack your metrics, so you know for the future
© 2006 Linda Urban 69
Examples from my experience Examples from my experience (1)(1)► Simple project, outputs to PDF, HTML, CHMSimple project, outputs to PDF, HTML, CHM
No context-sensitivityNo context-sensitivity One main writer, 2nd contributorOne main writer, 2nd contributor Information already fairly modularInformation already fairly modular Info not too complex (“software user guide”) Info not too complex (“software user guide”) Recurring projectRecurring project Incremental improvements in HTML outputIncremental improvements in HTML output
► Recurring “Extra” time (beyond requirements for one Recurring “Extra” time (beyond requirements for one deliverable)deliverable) ½ day to 2 days for template (nothing fancy, but always ½ day to 2 days for template (nothing fancy, but always
some change)some change) 1 to 2 days for reviewing content for linear-to-modular 1 to 2 days for reviewing content for linear-to-modular
adjustmentsadjustments ½ day to 1 day for cross-references½ day to 1 day for cross-references 1 to 1 ½ days production each time outputs required1 to 1 ½ days production each time outputs required
© 2006 Linda Urban 70
Examples from my experience Examples from my experience (2)(2)► Complex project (3 guides, 540 pages), outputs to PDF, HTMLComplex project (3 guides, 540 pages), outputs to PDF, HTML
New material, new design, known toolNew material, new design, known tool Context-sensitive help, software had multi-page wizardsContext-sensitive help, software had multi-page wizards Complex content for administrators including configuration, setupComplex content for administrators including configuration, setup 3 writers, one highly-experienced with single-sourcing, one experienced 3 writers, one highly-experienced with single-sourcing, one experienced
with online help, one “print” writerwith online help, one “print” writer
► ““Extra time:” 50% more per page than similar project “only for print”Extra time:” 50% more per page than similar project “only for print” Included all extra tasks (adjustments to writing, editing, coaching, cross-Included all extra tasks (adjustments to writing, editing, coaching, cross-
references, project management)references, project management) 1 week for initial prototype, but ongoing adjustments1 week for initial prototype, but ongoing adjustments 1 day production each time outputs needed 1 day production each time outputs needed
(each review)(each review) 1 week final production1 week final production
► Future updates should see more time-savingsFuture updates should see more time-savings
► Note: Complexity of this project not only due to single-sourcing, so Note: Complexity of this project not only due to single-sourcing, so not true metrics test to add just for single-source costs (this project not true metrics test to add just for single-source costs (this project included multiple changes in product, project scope, stakeholders)included multiple changes in product, project scope, stakeholders)
© 2006 Linda Urban 71
Where the surprises lurk when Where the surprises lurk when estimatingestimating► From paper to online…From paper to online…
Underestimating learning curve for writers from Underestimating learning curve for writers from linear to modularlinear to modular
Underestimating required editingUnderestimating required editing
► From online to paper…From online to paper… Underestimating additional topics needed for printUnderestimating additional topics needed for print Overestimating the tool, underestimating template Overestimating the tool, underestimating template
changes or post-conversion stepschanges or post-conversion steps
► Both directions…Both directions… Amount of rework required to adjust for another Amount of rework required to adjust for another
outputoutput Required “conditionalizing”Required “conditionalizing” Differences that reviewers/stakeholders wantDifferences that reviewers/stakeholders want
© 2006 Linda Urban 72
7. Test your solutions7. Test your solutions
►Review all outputsReview all outputs►QA all outputsQA all outputs► If you don’t, you riskIf you don’t, you risk
ErrorsErrors Conditional text settings that are set Conditional text settings that are set
incorrectlyincorrectly Cross-reference and link errorsCross-reference and link errors Linear references that don’t make senseLinear references that don’t make sense Topics that split at wrong pointsTopics that split at wrong points
© 2006 Linda Urban 73
8. Document design decisions, 8. Document design decisions, techniques, and processtechniques, and process► Important for your writersImportant for your writers
► Important for ongoing maintenance and Important for ongoing maintenance and updatesupdates Especially important if a different writer or team will Especially important if a different writer or team will
inherit the projectinherit the project
► IncludeInclude Additions or changes to your style guideAdditions or changes to your style guide Types of topics, with details about eachTypes of topics, with details about each Steps required in productionSteps required in production Quirky solutions to design issues (ex: changes to Quirky solutions to design issues (ex: changes to
macros in WWP) (What if you had to recreate?)macros in WWP) (What if you had to recreate?)
© 2006 Linda Urban 74
Project documentation takes Project documentation takes time, but is worth ittime, but is worth itIf you don’t, you riskIf you don’t, you risk►Making it harder for the documentation Making it harder for the documentation
teamteam►Reinventing the wheel next timeReinventing the wheel next time►Mistakes in single-sourcing in the next Mistakes in single-sourcing in the next
revrev►Losing cost benefits of having decisions Losing cost benefits of having decisions
already made and ready to be re-usedalready made and ready to be re-used►Required trouble-shooting to figure out Required trouble-shooting to figure out
how things were set uphow things were set up
© 2006 Linda Urban 75
A few resourcesA few resources
► Examine single-sourced examples Examine single-sourced examples (Dreamweaver, WebWorks Publisher, Books (Dreamweaver, WebWorks Publisher, Books with Content on CD, Others…)with Content on CD, Others…) What decisions did they make?What decisions did they make? How effective are they?How effective are they?
► Discussion lists with relevant topicsDiscussion lists with relevant topics Single-sourcing SIG (STC)Single-sourcing SIG (STC) WWP-Users (Yahoo Group)WWP-Users (Yahoo Group) AuthorIT Users Group (Yahoo Group)AuthorIT Users Group (Yahoo Group) HATT (Yahoo Group)HATT (Yahoo Group)
© 2006 Linda Urban 76
Books with related informationBooks with related information
►Standards for Online Communication Standards for Online Communication (Hackos)(Hackos)
►Single-Sourcing: Building Modular Single-Sourcing: Building Modular Documentation (Kurt Ament) Documentation (Kurt Ament)
►Content Management for Dynamic Content Management for Dynamic Web Delivery (JoAnn Hackos)Web Delivery (JoAnn Hackos)
►Managing Enterprise Content (Ann Managing Enterprise Content (Ann Rockley)Rockley)
© 2006 Linda Urban 77
ConferencesConferences
►WritersUA (www.writersua.com)WritersUA (www.writersua.com)►STC InternationalSTC International►Content Management-relatedContent Management-related
IA SummitIA Summit From consultants (Hackos, Rockley)From consultants (Hackos, Rockley) GilbaneGilbane
© 2006 Linda Urban 78
Wrapping upWrapping up
►Thank you!Thank you!►Questions? Comments?Questions? Comments?►Contact Linda UrbanContact Linda Urban
[email protected]@earthlink.net www.urbancreations.comwww.urbancreations.com