Top 4 steps from manuals to topics

A little bit of planning ensures you get clean, manageable topics from your conversion of user manuals.

While most help authoring tools support importing Word documents, there’s more to getting re-usable topics out of user manuals, as I’ve found out. I’ve spent the last few weeks converting 3 related Word manuals of 360 pages into 400 topics in Madcap Flare – though I believe that the process below applies to other tools as well.

The aim was to merge the contents from separate Word-to-PDF manuals with the online help topics into a single sourcing repository from which we can create both online help and manuals.

My two key lessons of the conversion are:

  • Plan first, execute second – several hundred topics are too many for trial & error and picking up the pieces later.
  • Do each task as early as possible – some Word idiosyncrasies are hard to clean up after the conversion.

And here’s how I did it in 4 steps:

 

1. Start with plans

The whole conversion exercise benefitted much from a couple of designs that I followed:

  • An information model
  • A folder structure for my topics

The information model defines the 4 topic types we have and what each type contains internally. It’s basically “DITA, without the boring parts” about which I blogged previously.

The folder structure divides my one Flare project into several sub-folders, so I don’t have 400 topics in one heap. Instead, I now have 13 sub-folders which divide up my topics by topic type (concept, task or reference) and even by task type (initial setup or daily workflow). That makes it easier to manage the topic files.

2. Prepare for the import

Once I had the basic structure to organize topics and their insides, I prepared my Word manuals, so I didn’t have to deal with a GIGO situation, where I get Garbage In, Garbage Out.

First, I edited the documents into topics, so each section could become either a concept, task or reference topic – or an auxiliary topic which ensures that the chunks still flow nicely when you read them in the future manual output. I also ensured that section headings indicate topic contents and type:

  • Concept topics use noun phrases as headings
  • Task topics start with an imperative

Then, I cleaned up the documents. You can convert unstructured Word with layout applied in styles, modified styles and manual formatting into topics just fine, but it will give you unmanageable content and endless grief. So do your future self a favor and dissolve all modified styles and manual formatting.

3. Import

Thus prepared, I’ve found that Flare’s built-in Word import is very good, consistent and reliable if you throw well-structured Word documents at it. Only tables didn’t import well (or I couldn’t figure out how to do it), so I re-styled them in Flare.

If you’re a stickler for clean topics, you can go ahead in Flare and clean out unnecessary remnants:

  • Remove Word’s reference tags in cross references by replacing *.htm#_Ref1234567″ with *.htm”
  • Remove Word’s Toc tags in Flare’s table of contents by replacing *.htm#_Toc1234567″ with *.htm”
  • Remove Word’s Toc anchors in topics by deleting <a name=”_Toc*”></a>

4. Adding value to topics

At this point, I had a pile of 400 clean topics, but no added value from the conversion yet. That came from additional tasks:

  • Dividing up topic files into the folder structure, which makes hundreds of topic files manageable.
  • Assigning a topic type to topic files (Flare lets you do that for several files at once, so this was very fast), which makes the content intelligent, because topics “know” what they are.
  • Assigning in-topic elements (as div tags) to topic paragraphs according to the information model, which allows you to identify and reuse even parts of topics, for example, instruction sections or example sections.
  • Creating relationship tables for cross-references into relationship tables where feasible, which ensures that links are easier to manage and to keep up to date.

Your turn

Have you done a similar conversion? What were your experiences? Did you do it yourself or with an outside consultant? Feel free to leave a comment.

Advertisements

All aboard! Onwards to structured authoring!

Our team of technical writers is embarking on a journey towards structured authoring. With 10 writers, we’ll move from an unstructured Word to PDF/CHM environment to a structured Flare to WebHelp/PDF environment. Or I should say “semi-structured”: We do have an information model based on DITA, but we won’t actually be able to enforce it with Flare (which we knew before we chose the tool).

It’ll be an interesting cruise, to be sure! Four writers already apply topic-based authoring rather than the previous free-form documentation guided mainly by common sense. The others have had training, but no real opportunity to write topics continuously. We have drafted tighter new processes to draft, write, review and edit topics to replace the previous loose processes of writing and reviewing, but they are not in place yet.

And then there’s the new tool, of course. Only one of us has worked with Flare before. Many of us are excited about getting Flare. Some really like it – what we’ve seen in several demos so far. Others just really loathe the current writing environment.

“Regarding the pain of others”

So as we’re about embark, I’ve been looking out for others who’ve taken the trip before. Scriptorium’s State of Structure webcast has been very helpful: Its results of a survey among 200 tech communicators helps to position us in relation to others who are currently implementing structured authoring or considering it. It also collects some mistakes respondents have gone through. I’ll just be quoting a few select points, but the whole webcast by Sarah O’Keefe is totally worth checking out, so thanks to Scriptorium for making this webcast available!

Reasons

The top reasons why survey respondents (consider to) move to structured authoring made us nod emphatically: Reuse, consistency and cost savings are also at the top of our wish list of achievements. Looking ahead, it’s promising that the majority of respondents achieve these goals.

We’ll also take other goals that respondents achieved, whether it’s to automate processes or to reduce content (oh, yes, please, we’re not even exactly sure how much redundant, almost identical content we have). So far we’re confident, we’re not only doing the right thing, but doing it for the right reasons, too!

Efforts

Savings have their own price, of course. Sarah’s survey confirms several cost points we’ve already identified in the project.

  • Converting legacy content is a biggie for us, simply because we currently have a lot of stuff.
  • Redefining output layout will take time, but will be worth it given what Flare is capable of doing with CSS in both web and print outputs.
  • Integrating a new system with its writing and publishing processes into our product and workflow systems will also take some time.

Mistakes

Mistakes have been made by others before us, and we’ll have plenty of chances to make our very own mistakes. If we’re lucky, we can avoid repeating the mistakes of others:

  • Planning and project management cause problems, maybe because most companies lack the experience of major documentation overhaul projects. Sarah specifically mentioned the lack of understanding of the project scope and of the need for testing. So we’ll look through our project plan again and ensure that the estimates are plausible.
  • Converting legacy contents can also get you into trouble, especially when you convert something that’s less than structured. It doesn’t help if you reserve too little time to do it or get inexperienced people to do, whether it’s off-shore labor or student helpers. That’s sound advice: GIGO (“garbage in, garbage out”) can certainly endanger the expected benefits. A new tool can help us be more efficient, but we still have to learn and apply structured writing in topics. So this confirms one of my two tech comm dogmas: Don’t get a new tool to fix your processes!

Setting out

What do you think? Is our crew well-equipped, given a tried and proven method, well-defined processes, a new tool and the words of warnings above? If you have additional advice, please leave a message.

Recommended video: What’s new in MadCap Flare 7

Here’s a timed summary of the “MadCap Flare V7 – What’s New Demo” and more resources that review the latest Flare release.

The 55-minute video is by Mike Hamilton, VP Product Management of MadCap Software, recorded on March 3. The audio is not spectacular, but other than that it’s a lively, engaging demo. You’ll find the video on MadCap’s webinar web page.

I’ve prepared this transcript summary, because I wanted to refer to individual “chapters” of the demo. I like Flare and MadCap Software, but am not affiliated with them, other than as a fan and past and future user.

More MadCap resources

Flare 7 covered elsewhere

MadCap Flare V7 – What’s New Demo, Topics & Times

0:00 Webinar preliminaries

1:30 Find more info about Flare 7 at the MadCap web site

3:40 Agenda

  • General
  • Editor
  • Workflow/Team Environments
  • Viewing/Testing
  • MS HTML Help Enhancements

5:20 1. General Topics

  • Accessibility Enhancements
  • Reports Engine (which is new, not MadCap Analyzer)

6:50 General > Accessibility Enhancements

  • Web help and PDF enhanced for users with disabilities
  • Add screen tips to graphics for screen readers
  • Optional build warnings remind you of accessibility issues: missing alternate text, etc.

10:50 General >Reports Engine

  • Create custom reports about all files in project
  • Build a report from scratch or use included report templates
  • Examples: Show all conditions in report files, show all topics with changes and comments

14:30 2. Editor Enhancements

  • QR Codes
  • Equation Editor
  • Vector Graphics
  • Auto Suggestion
  • Alias Editor Enhancements
  • Table Enhancements
  • Customize Flare UI Grids
  • Remove Inline Formatting
  • Shortcut Buttons (Snippets/Variables)
  • Paste Options

15:20 Editor > QR Codes

  • QR codes are smartphone-readable (“square barcodes”)
  • Include an URL, e-mail address, or text in print output
  • For online output, you can make the barcode clickable…

18:05 Editor > Equation Editor

  • Supports MathML code
  • Formulas are inserted in author mode as stylable, scalable vectors
  • Formulas render as lossless, non-blurry postscript in print & PDF
  • Formulas render as graphics online

20:45 Editor > Vector Graphics

  • Supports inserting SVG, PS and EPS graphics in topics
  • They allow lossless scaling
  • Render as lossless, non-blurry postscript in print & PDF
  • Render as graphics online

24:10 Editor > Auto Suggestion

  • Can be turned on and off
  • Reminds you of existing snippets (=sub-topics) and variables (=module names)!
  • Makes reuse of snippets and variables easy
  • Supports added common phrases, too

26:25 Editor > Alias Editor Enhancements

  • Completely reorganized
  • Shows complete, incomplete and missing aliases
  • You can auto-generate file IDs from pattern

(29:20 You can move tabs of open pages around.)

30:30 Editor > Table Enhancements

  • In Flare editor, you can convert text to table and table to text
  • (Be patient with Mike; he needs a minute to find the feature in the GUI…)
  • You can also merge tables

34:15 Editor > Customize Flare UI Grids

  • You can customize any dialog, any GUI grid in the Flare editor for custom column layout and appearance

35:50 Editor > Remove Inline Formatting

  • You can remove inline formatting easier, without highlighting exactly

37:45 Editor > Shortcut Buttons (Snippets/Variables)

  • Icons in text workspace provide faster access to selection of snippets and variables

38:50 Editor > Paste Options

  • Paste text as paragraph, list, table

40:00 3. Workflow/Team Environment Enhancements

  • SharePoint Integration
  • Subversion Integration
  • External Resources
  • Review/Track Changes

40:15 Workflow/Team Environments > SharePoint Integration

  • You can integrate Flare projects into SharePoint or import any SharePoint file into Flare

41:15 Workflow/Team Environments > Subversion Integration

  • Subversion is now directly integrated
  • Without 3rd party plug-ins, such as Tortoise
  • This is now like Microsoft Team Foundation Server and Visual Source Safe

42:15 Workflow/Team Environments > External Resources

  • You can use any external resource/file in Flare
  • … even if it’s not part of any Flare project
  • Link to any network file that’s accessible
  • However, these resources are then outside of Flare’s source control

44:30 Workflow/Team Environments > Review/Track Changes

  • Comments and Track Changes essentially acts as in Word
  • With multi-colors, strike-through
  • Several users can see each other’s edits
  • You can accept/reject changes individually or accept/reject all
  • This works only in the Flare editor and in Contributor (previously X-Edit)
  • It doesn’t work in any output

49:10 4. Viewing/Testing Enhancements

  • Chrome
  • Preview Any Format
  • WebHelp Output – Choose Browser

49:10 Viewing/Testing > Chrome

  • Fixes bug that you couldn’t view (any vendor’s!) local web help in Chrome browser

50:20 Viewing/Testing > Preview Any Format

  • You can quickly select to preview the topic in any defined target format, not just one selected format
  • Easier, more realistic previews

52:30 Viewing/Testing > WebHelp Output – Choose Browser

  • You can quickly check web help output in any installed browser: IE, Firefox, Chrome, Safari

54:10 5. MS HTML Help Enhancements

  • You can import a .CHM file as a Flare project, including the TOC and index

55:30 End