Technically Speaking

In my opinion, Adobe Framemaker has a major flaw: it doesn’t support external sytle sheets. External style sheets could be huge. Maybe I should explain.

One of the powerful things about FrameMaker is the ability to create templates that you can reuse across all your documents. For the current release of my product at work, I’m working on about 200 pages of printed documentation, spread out across four books and about fifteen separate documents. Before I started my project, I created a template book. In my template book I created a template chapter, and defined all the styles, or rules for formatting the text.

When most people use a word processor, like Word, they apply ad-hoc formatting. This means that when you want to create a heading, you select the text and you apply bold formatting, or change the color, or change the font size. They follow this same procedure for every heading that they create.

Frame doesn’t like that approach. Rather, you are supposed to create paragraph formats (Word calls them “styles”) that you apply to the text. You have a number of styles (my guides currently have about 50 possible styles) that cover everything from the body text appearance, to headings, to your title on your title page, to the style of the picture captions. Once these are pre-defined, you just select the paragraph, and apply the format. If you ever want to change the format, you just use the paragraph designer to apply the format. It’s pretty powerful, and it saves me a bunch of time, after the formats have been created and refined. However, here is where we encounter Frame’s weakness.

When you create a style, you apply it to the document’s template. When you create new documents, you base them off the template. However, Frame doesn’t remember that you based the document off of the template, so if you ever make changes to the style in the template, you have to open up every separate document and import the style information. Every document contains its own style information, so if you change it in one document, you have to import those same style settings into all other documents to keep them consistent.

I wish Frame supported external style sheets. HTML allows you to use external style sheets, and they work really well. With an external style sheet, you have a separate document that contains all the style information. At the beginning of an HTML document, you create a connection between the HTML file and the style sheet. When the page is delivered to the web browser, the web browser gets the text from the HTML file, and then formats the text according to the style information in the style sheet. You can have multiple (actually an unlimited number of) HTML pages that use the same style sheet, If you want to change the formatting of a particular heading, you open the style sheet and you cange the formatting options. Remember that individual documents don’t store formatting information; all the formatting information is derived from the shared, connected style sheet as the page is loaded in the brower. That means all pages are updated to the changed style as soon as the change is made in one place.

Frame doesn’t support external style sheets. In Frame, every individual document contains its own formatting information. Currently, if I want to change the style, I open up the template document for the type of document I’m working with. I make the style change, and then I save the document. Then, one at a time, I open every document I’ve based off that template, and I import the style information into that document. Its a labor-intensive process, and it is totally unnecessary. If Frame supported external style sheets, I could just open the external style document, make my change, and go on my way, knowing that all the styles would be “updated” as each document was opened.

So, if you are listening Adobe, please, please, please consider adding external style documents in the next release of Frame. It will literally save me hours of time during each release cycle of my product documentation.

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.

I write this post in defense of the color-blind users of the world. First, let me give you some background.

I worked previously for a company that produced language learning software. A writer was added to my team, and after a couple of weeks of using the software, he complained that while doing a specific activity, he couldn’t tell that he had matched the items incorrectly. He asked me how he was to know that it was wrong. I explained that the big red “X” next to the item showed him that it was wrong. He indicated that he couldn’t see a red “X”, but that it was probably because he is colorblind.

Since then I’ve been much more aware of color-blind issues as I work with computer software and as I design documentation. Thus, when a question arose recently on the Techwr-L list regarding document design and color, I decided to chime in with my own response.

In case you didn’t read the threads, here is a summary. The original poster was talking about document design in Framemaker, and wondered if there are people that use blue text to indicate a link in their Frame documents. A couple of people responded to the thread and said that they do use blue text to indicate links. I thought it prudent to point out that for good document design you shouldn’t just use color to indicate that a span of text is a link. Problems include that users who are colorblind may not be able to differentiate the link, and users who print the documentation on a black and white printer won’t be able to tell that the text was a link.

My response was challenged by one of the users on the list who wanted to know why I care how a link is shown in a printed doc. After all, he asked, “Is there a way of clicking a link from a printed page?”

Besides thinking that the question was stupid, I was annoyed that my attempt to point out a principle of good design had been brushed off as if I were to dumb to contribute to the conversation. I decided to explain my comments further, which I did.

Here was my response:

Well, obviously they aren’t going to click a link from a printed page. Give me a little bit of credit here. As you can see from my answer, I was giving a general warning about using color; I wasn’t giving a specific response to obair81’s original question.

And in my own defense, the advice I gave is good general advice from a design perspective.

When you use only color to indicate that something is different about a particular string of text, then you run the risk of alienating part of your user audience. My first example dealt in general with the area of accessibility. Of particular concern are colorblind users who may have difficulty differentiating the color from the rest of the body of text. My second example dealt with the inherent inconsistencies in the way end users access our documentation. Some use it online and can follow links while others print the documentation to use as a reference.

If the user of the printed document can’t differentiate the subtle color shift to indicate that there is a link in the on-line version of the document, then your user will not benefit from the knowledge that additional information is readily available via a link in the electronic copy.

So in reference to your question, John, no I don’t expect a user to click on a link from a printed page. But I do think that I have a responsibility as a designer and writer to provide documentation via a method that doesn’t inherently alienate users who either have accessibility issues, or choose not to read the documentation on the screen.

In general, this is good advice. You’ll have to adapt it for your users based on what you know about them. If you know that you have non-colorblind users who will never print the documentation for any reason, then by all means, use color alone for your links. If you can’t guarantee this scenario, then you should at least be aware that your choices are limiting your documents usefulness to potential users.

I stand by my comments. When you are designing documentation, you should never use color as the sole indicator of some additional information without first considering the risks involved in alienating some portions of your audience.

After all, somebody has to stand up for our color blind friends out there!

(You’re welcome, Dave.)