Blogging has become difficult recently. As I have worked at my new job, I’ve found that I’m running around from task to task at such a pace that I haven’t had much time for blogging. It’s a great thing, work-wise. It is interesting and engaging, which I love. It’s not so good for my blog. Last night Christina said, “I can’t wait to see your next entry.” Then she suggested that I set aside a specific time to blog, or I won’t get it done. Now, I’m on the train. I don’t have an internet connection, so this is a good use of my time.
I found a way to bring some light into the cave. I purchased a swing arm desk lamp. I can get it right up under my bookcase, over my computer. Now I can actually see what I’m working on, which is a benefit.
I am having a great time at my new job. I’m finishing the installation guide for the newest iteration of the company’s software. It’s about twenty pages long and I’m excited to get it finished… My first project.
From a technical writing perspective, I’m learning a lot working as a lone writer on a new project. First, It’s been interesting to try to figure out the resources I’d need to complete a project before I understood the scope of the project. I learned that scope is the horse, and resources are the cart that must follow. One of the first things the company wanted from me was a list of the software that I needed to get my job done. For my main document publishing tool, I was debating between InDesign and FrameMaker. The problem was that I hadn’t really looked at the software, nor had I seen the documentation requirements for the project. So I was working blind as I selected the software packages I needed.
I chose InDesign because I think it is a powerful publishing tool. And it came in a suite, packaged with PhotoShop, and Acrobat Professional, in addition to others. In the end, I was cheaper to buy the suite and get all the software than it would have been to buy just Photoshop and Acrobat Professional, so if you look at it that way, InDesign was free. The problem was that after I had ordered my software, I had a meeting with the product manager where for the first time I understood the scope of the project and understood the documentation requirements. It became clear quickly that some of the doc requirements wouldn’t be met by InDesign. In particular, InDesign’s support for the following features was lacking:
- Running Headers and Footers. The documentation template, which I am expected to use, has running headers and footers that reflect the heading levels in the document. So the document title always appears on right page headers. The chapter name always appears on left page footers. The text of the most recent Heading 1 always appears on the right page footer. InDesign doesn’t do running headers/footers, so I’d have to do these manually at the end of my production cycle — the very last step, for fear that the document might re-flow if any changes were added.
- Cross References. FrameMaker has a feature that lets you cross reference other headings in your book. So, if I was writing about a feature, and wanted to insert a reference to another chapter that deals with a corollary feature, I can insert a variable that pulls the heading text I want to point to, and the page that heading is on. If the document re-flows, or if the heading text is changed, the cross reference link is updated. So if I’m writing installation instructions, and I want to tell the user to see chapter 9 for more information on account management, I can enter a cross reference to do so. In InDesign, I’d have to just type the text in manually. If the chapter number changed, I’d never know all the places in the documentation that pointed to it.
- Conditional Text. The company I work for has government contracts and private contracts alike. There are certain documentation requirements for government contracts that we aren’t required to include in our regular product version. The software is also customizable for specific clients. With Frame’s conditional text, I can add all the information into one guide, say the administration guide. The government-contract-specific text gets marked with a conditional text marker. When I print, I can turn On the government text, or I can turn it OFF. I can make two versions of the manual from the same file with a couple of mouse clicks. The table of contents and cross references are all updated throughout the guide. I don’t have to maintain multiple guides for government versus private sector clients.
So, I had to go back to my manager and request the latest version of FrameMaker. I’d love to use InDesign, and I probably will use it for Quick Reference cards and other layout-intensive documents, but for my book-length documents, my documentation requirements are better met by Frame.
Yesterday I asked my manager if he thought they were going to approve the Frame upgrade. He told me that if I had requested it with my initial software list, it would likely have been approved.But since it wasn’t on the initial request, there was a chance I might not get it.
Lesson learned. The first of many, I’m sure. After all, I’m a lone writer, foraging my way through territory I’ve never visited.
Editor’s note: (Oct 2008) When this post was written more than two years ago, my options were between InDesign CS2 and Framemaker 7.2. Technologies have changed since then, and this post should be read in context of the features that were available in those versions of the products. I had to make my software purchase based on those features, and have since moved away from both tools in favor of an XML-based authoring solution, MadCap Flare.