Terry Smith

Terry Smith is a technical consultant, communicator, and Senior Member of the STC Carolina chapter, passionate about the tools and processes that make it possible to create high-quality documentation.

Terry gave a much anticipated talk about “Online Review with Adobe Acrobat” during the STC Conference on May 5th. You can follow her on twitter at @tesmith

What are the three things you love the most about being a technical writer?

The thing I love most about being a technical communicator is knowing that I have made a product easier to understand and use. Writing well challenges me; clean, simple writing is hard work! I like setting up the document structure and formatting, too.

Although you didn’t ask, I must add that what I dislike is the need to drop an unfinished project to work on something that suddenly became urgent. Online reviews help me stay organized because I can see exactly where I stopped. I can even see the date of the last change, which really helps me restart tasks quickly.

If you were going to a desert island and were only allowed to bring DocBook, DITA, or nothing at all, what would you choose and why?

Which would be better for smashing open a coconut? On a desert island, I would want the most versatile tool possible, of course. I would definitely want some kind of structure. If nothing at all means I could create my own XML structure from scratch, I’d probably choose that.

Given the choice between DocBook and DITA, I’m torn. DocBook is mature and has elements for just about anything necessary for print. DITA is most suited for online documentation; it’s the up-and-coming youngster that claims to be able to do everything with ease via specializations. DocBook might be too much baggage for carrying around a desert island. DITA specialization is never as easy as it sounds. Hmm. Perhaps I had best just pack a knife and a Wilson volleyball.

During your typical documentation project, which tool or software do you use the most, which one do you prefer using, and which one do you wish existed?

The tool I use most is FrameMaker. For any workflow that includes PDF output, FrameMaker is still my tool of choice. FrameMaker handles structured documentation, including DocBook and DITA. The tool I use most after FrameMaker is Adobe Acrobat, which supports online review.

Of course, FrameMaker has its idiosyncrasies. In FrameMaker, the document structure and its formatting are wedded and it’s not always easy to reconcile FrameMaker’s needs with XML’s needs. The view in the document window is identical to the PDF output although you can make the element tags visible or open the structure view in a separate window. In a dedicated XML editor like oXygen or XMetal, while writers don’t work in a document view that is a perfect match to the PDF output, writers can see a code view of the underlying XML that isn’t possible in FrameMaker.

The perfect tool doesn’t exist yet, but I would like a tool that lets me see a code view of the underlying XML and also produces beautiful PDF output easily.

If you had a magic wand that could change one thing about the documentation reviewing process as you know it, what would it be? Do you have a fun anecdote to illustrate life without a magic wand?

If I could wave my magic wand, then I would place a spell on the reviewers to make them review the documentation! Every technical communicator knows that the closest thing to magic fairy dust is to entice reviewers with baked goods or chocolate.

In all seriousness, I do wish I had a single process that worked for everybody. While I am a fan of online reviews, not everyone is. Programmers and subject matter experts who are in remote locations tend to prefer online reviews. Editors and others who are accustomed to the convenience of writing on a stack of paper despise online reviews, because the online tools are comparatively slow and clumsy.

I have yet to see an online review tool that would allow a reviewer to compare two or more pages at one time like can be done by spreading out paper pages. I most often use Adobe Acrobat for review because it’s the most like reviewing on paper, which makes it easier for me to get my reviewers to use the tool.

How does online collaboration work in your documentation projects? Do you have a favorite LiveTechDocs feature?

When I start an online review, I send the PDF file by email or post it to a location where all the reviewers can access it. The reviewers add their comments, respond to each other’s comments and my questions, and then I mark the comments as complete when I incorporate them.

The reviewers can see that I have changed the status of the comment and the date when I did that. Most of the time, I cut and paste the comments into the original document. With the latest version of Adobe Acrobat, I can automatically import some types of comments directly into the FrameMaker source file and then use FrameMaker’s track changes features to accept or reject the imported comments.

Even if I import the comments automatically, I still change the status of each comment in the original document to show how I handled the comment. It’s a manual step, but it lets the reviewers know the status of their review comments before the next review cycle and serves as a permanent archive of when the changes were made.

I have begun evaluating LiveTechDocs. My favorite feature is the intuitive web interface. Uploading documents into the repository is a snap. LiveTechDocs has some workflow support: reviewer adds comments, writer incorporates comments, and project manager signs off on comments.

As an online collaboration for technical documentation review expert, what pieces of advice would you give us at LiveTechDocs to help us delivering an optimal solution to our users?

The workflow support in LiveTechDocs is nifty. I realize that LiveTechDocs is still in beta; ideally, LiveTechDocs would validate any XML against a supplied DTD. If LiveTechDocs did this, then it would definitely be worthwhile to consider for review of any structured documentation!