Download pptx - Converting legacy content (LavaCon 2016)

1

What should you do with your legacy content?

A writer’s perspective

© Adam Sanyo, 2016 LavaCon Dublin, 2016

© Adam Sanyo, 2016 LavaCon Dublin, 2016 2

AgendaPart 1: Adopting DITA• Reasons why companies go for DITA• Adoption scenarios and costsPart 2: Using DITA• Minimalism and writing in DITA• Metadata and other Part 3: Legacy conversion• Creating a team for the project• Creating authoring and end-to-end workflows• Costs, benefits, problems• Business case and workflow examples


My backgroundCelebrating 6 years this week

• Six years of experience in technical writing.• Worked on two different migration projects.• Degree in English and Linguistics.• Currently working for ARM as an

information developer.• “Love at first sight” when encountering

DITA in 2010.

4

PART 1: Adopting DITA


WHY?


Why do companies decide to adopt DITA?

Because they want to achieve any of the following:• Re-use content across products• Reduce costs• Share workload and increase productivity


DITA adoption scenarios• The company wants to manage a large document set from a

component content management system (CCMS) and wants to get rid of authoring silos.• Different authoring teams create similar content and some of that

content could be reused.• The company wants to translate its document set effectively and

wants to reuse translations over time.


DITA adoption costsYou will need:• A good CCMS• A business case• Experienced authors• Lots of training for authors• Money for specialist consultants


PART 2: Using DITA

HOW?


Is structured writing a good thing?

YES, because of:• Scalability• Minimalism

BUT:• Not suitable for every product• Authors may find it hard

10

What is the key to quality structured content?

Metadata

Transparency

Reusability

• Every small piece of content must be searchable.

• It is the essential that writers know the extent of the existing content.

• In a structured model, you can reuse content across different publications and inside your products as well.



Where does legacy content come into the picture?

• Have a standard workflow first integrate legacy conversion into it• Analyze existing content• Do a content audit if needed


PART 3: Legacy conversion

WHY?HOW?WHO?


How do you start off a legacy conversion project?

Things you need at the start:• CCMS• People with structured authoring experience• Money to invest• A prototype project• A conversion process

14

Authoring decisionsLet us assume that you are using the standard DITA framework (task-concept reference topics) and one or two extra topic types on top of that.

• Chunk your content into topics

• Start with task topics

• Create a reuse strategy

• Decide the level of deviation from the original content



General reuse rules• Gain flexibility by using keys• Reuse block elements • Rewrite two or more similar

topics if they become reusable after that


Is it expensive to migrate content?

Yes, but it can pay off if:

• You reuse the content you convert

• You create a scalable solution

• You know what you are doing

Standard costs:

• Software (authoring tool)

• CCMS

• Specialist cost

• Lost time


What are the measurable cost savings?

Conversion process success criteria• Reduced translation cost • Reduced authoring time •Documentation is used more

extensively

CostTime

Productivity


Cost and resource saving tips• Outsource some of the easy but manual tasks.• Distribute tasks among team members based on their strengths.• Make sure that everyone knows how the converted documents

will be reused.• Spend more time and effort in the planning stage.

19

Usual problems and solutionsProblems1. The team is reluctant to move into

DITA.2. There are resource constraints.3. The business case is not strong

enough.4. Knowledge sharing is not strong

between teams (there is a risk of “reinventing the wheel” cases).

Solutions1. Provide training and nominate DITA

champions who can push the team forward.

2. Create a small but scalable prototype project first as a test.

3. You may need to reconsider the scope of your legacy conversion.

4. Pull in members from different teams to improve knowledge sharing.


How different groups benefit from a migration project?

Management

• Lot of data is available to plan structured writing projects

• Can boost confidence in your team after the project

• Helps to remove silos

Writers

• It is good to have DITA experience in your CV

• The writing role can be expanded

• Better integration with other teams

Suppliers / 3rd party

• Easier to calculate revenue for translation requests

• Business expansion opportunity for consultants

• Recurring work for XSLT experts


21

Business case examples disclaimer

The following business case examples are presented by me based on the observations I had in the project and the data I was able to gather.



Business case example 1Overview:

The company manages structured FrameMaker documents for three of its products (by 2.5 technical authors). The content is translated into 14 languages. The total size of the English content is roughly 2000 DITA topics.

Business case:

Adopting DITA and a DITA-based CCMS would improve translation management and reduce translation costs.

Results:

Content conversion to DITA was successful, but costs were not reduced significantly. It was because the extra cost of adopting DITA and the maintenance of the CCMS was as costly as the money saved thanks to the improved translation process.


Business case example 2Overview:

The company manages structured FrameMaker documents for several products. The size of the content is huge (tens of thousands of topics) and is managed by several authoring teams.

Business case:

Converting content to DITA would improve content reuse across products and authoring teams.

Results:

The content conversion from FrameMaker to DITA was partially successful as dozens of documents were converted. However, the reuse mechanism must be improved (for example, with improved metadata tagging) to see how documents can reused across different products. A separate project was kicked off that focuses on improvements helping with content reuse.


Legacy conversion process example

1. Identify important documents that need to be converted.

2. Create a process for future conversion jobs. Main process steps include:a. Cleaning up the initial source files

b. Using the conversion script

c. Post-processing the converted files

d. Reviewing the files

e. Publishing and sharing the finalized files

3. Create a script that converts the legacy document into DITA with little post-processing required.

4. Estimate the effort required for each conversion (including the post-processing effort of each document).

5. Find technical resources for the conversion jobs.

6. Monitor how converted documents are reused.


We have about 10 minutes left, so it is time for…

Q&A


Contact information

Adam [email protected]


Image references• Creative Commons license for images from Wikipedia• Coins: www.bestfinancenetwork.com • Writing flowchart: own work• Building blocks: www.softwareag.com • Technical writing chart: www.idratherbewriting.com

http://www.bestfinancenetwork.com/

http://www.softwareag.com/

http://www.idratherbewriting.com/