1 Avoiding Pitfalls When Single- Sourcing Print and Online Linda Urban WritersUA Conference 2006...

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


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


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)


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!


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


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


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


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


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


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)


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


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?


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


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


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


11

22

33

Portions of the Portions of the user guide user guide belong in helpbelong in help


22

11

33

But in the help, But in the help, a different a different order is order is appropriateappropriate


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)


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?


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?


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?


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.


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


A Reference A Reference Topic in PrintTopic in Print


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.


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


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


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


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


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


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


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


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


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


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


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


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…


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


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?


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


Moving a long Moving a long reference reference section from section from print to onlineprint to online

One ExampleOne Example


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


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…



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?



3. Expanding 3. Expanding headings headings

Scannable Scannable and flexibleand flexibleWon’t show in Won’t show in print Index issues print Index issues


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


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…


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?


An example An example from from QuickenQuicken


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)


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.


PDF page of PDF page of the expanding the expanding exampleexample


This pattern This pattern using using expanding expanding sections is sections is straight-straight-forwardforward


PDF page of PDF page of the expanding the expanding exampleexample


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


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


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


““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)


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


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


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


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”


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)


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


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


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)


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


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


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?)


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


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)


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)


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


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

Date post:	12-Jan-2016
Category:	Documents
Upload:	joel-lane
View:	213 times
Download:	0 times

1 Avoiding Pitfalls When Single- Sourcing Print and Online Linda Urban WritersUA Conference 2006...

Documents