Using Conditional Text and Boilerplate with Adobe FrameMaker
January 6, 2005 by John Hewitt · 1 Comment
Subject Matter Experts
On this project, I provided formatting and editing support for a group of subject matter experts (SMEs) who were putting out a new product. There were several difficulties involved with the project. To begin with, the subject matter experts were not particularly interested in the project. While the product would be new to the market, it had been in development for several years, and most of the experts were now working on a newer revision of the product. In other words, the version that was going to market would immediately be obsolete, and most of the work now focused on the next step rather than the current piece.
Another challenge was that no one was willing to step up and be the document owner. This problem was deeply frustrating for my supervisor, who has been dealing with these documents much longer than I have. The document consisted of three volumes containing ten chapters apiece. While the individual chapters had SMEs who were responsible for them, the overall document had no leader to take charge of putting the book together and making sure that the SMEs, who viewed the document team as a nuisance and said so, to provide the required support.
Boilerplate
My task was to go through each of the chapters and make sure they conformed to the boilerplate. The boilerplate was a set list of sections and section content that each SME had to match to their piece of the product. I had nothing to do with the development of the boilerplate, and I did not have a particularly high opinion of the way it had been set up, but I had to enforce it.
The other difficulty with my part of the project was that this was my first exposure to this product. It was a highly technical piece of hardware, and there was no time for me to devote to learning about it. My job was to go through each document, fix what I could, and put notes by anything I did not know enough about to fix on my own.
Another challenge was that the SMEs had frequently strayed from the boilerplate. The boilerplate had 21 different sections, only one of which was optional. In almost every chapter, the document had both missing sections and sections that were not part of the boilerplate. I would insert any missing sections (with notes about adding content) and flag any non-boilerplate sections. I would also give my best guess to the SMEs about where the information belonged. Finally, I made sure everything was in the correct order.
After I dealt with the section issues, I focused on the content issues. For example, one section in consisted of sets of tables. The SMEs had a choice between two sets of tables they could use to input key product data. If their part of the project used items from the A list, they were supposed to use table A. If their part of the product used items from the B list, they were supposed to use table B. In almost every case, the SMEs used the wrong table, leaving gaps where their information did not conform to the columns of the tables. In each case, I had to reformat the data to fit the proper table. This process was complicated because each item table linked to a summary table through a series of FrameMaker cross references that were dependent on paragraph types. Each paragraph had to change when the tables changed, and so I had to recreate all of the cross-references.
Conditional Text
Finally, there was the issue of conditional text. Conditional text is a Framemaker feature that allows writers to designate text to be hidden or displayed under specific circumstances. By doing this, you can use the same files to print out documents for different sets of audiences. In this case, we used conditional text to set levels of security. For example, highly sensitive information could be set to internal. Information that would go out to our corporate partners, but not to the public, could be set to secure. Publicly viewable information would be unconditional. This is just an example. In our case, we could apply about fifteen different conditions we could apply to text. According to the boilerplate, each section required at least one of four different conditions. I had to go through the document and reassign conditions until the documents conformed to the boilerplate rules.
Because the SMEs were neither eager to work with me nor compelled to work with me by someone on their side of the document, getting them to give me information was often difficult. It was even harder because, as a contractor, I have almost no authority. This meant that if I did not get a response I had to then escalate to my supervisor, who had to call the SMEs or their manager or their manager’s manager until we finally got a response.
As you can see, this was far from an ideal documentation project, although it is closer to the norm that most of us would like to think. As a contractor though, poorly planned, managed or executed projects rarely upset me. I have no stake in the outcome of the project. When I was a regular employee, watching a project go wrong would make me worry about my job and about the company as a whole. As a contractor, I only care about doing the best job I can for the client, no matter how misguided or mismanaged the project. If the client wants me to take ten weeks to accomplish something that should take a week, I can take ten weeks. After all, they pay me by the hour. Such is the life of a contractor.
A Technical Writing Project Using Adobe Acrobat and Adobe Illustrator
December 20, 2004 by John Hewitt · 2 Comments
Working with PDF Files
This week brought the first round of document editing. After spending last week looking for source files and confirming that at least thirty documents only have PDF files, I spent most of this week editing those PDF files.
PDF files are not intended for heavy editing. They are resistant even to light editing. In fact, one reason the company brought in a new contractor (me) was that none of the current staff were willing to attempt it. The rumor I have heard is that the contractor I replaced became “fed up” and he quit rather than take this assignment — good for him and better for me. I need the work and I do not mind the job.
Using Adobe Acrobat
As you probably know, you create PDF files using a program called Adobe Acrobat. There are some freeware translators out there that will turn a Word (or other) file into a PDF file, but Acrobat is the official program and it can turn just about any document into a PDF.
Using Acrobat, you can make minor edits to a PDF file, but Acrobat documents are very sensitive. Typing a single character can throw several lines off, destroy tables and cause all sort of other troubles. Alternately, it can be relatively uneventful and painless. You will not know until you type in that character.
Another problem with PDF files are embedded fonts. Because PDF files are meant to be read across platforms (Windows/Mac/Unix), many document publishers choose to embed particular fonts in order to ensure they get the desired look for their document. This means that the PDF file itself contains all the font information necessary to display and print that font, whether the viewer’s computer is equipped with that font or not. Normally, embedding fonts is a good idea, but it can make editing those documents (something you would normally never bother to do) complicated.
An important aspect of embedded fonts is that your computer will use the embedded font even if you have the identical font on your own computer. This means that, when editing, Acrobat may refuse to change or format a character because it uses an embedded font. You can work around these but the solutions are slow and tedious.
Using Adobe Illustrator to Edit PDF Files
One lesser-known solution to many of these problems is to use Adobe Illustrator to edit PDF files. Illustrator gives you much greater control over PDF pages and text formats. Illustrator has the ability to show individual blocks of text, which makes it clearer what you will change by typing something in. In Acrobat, you can only discover how much text is in a unit through trial and error. In addition, with Illustrator you can select a block of text and drag it to where you want it on the page (try doing that in Acrobat!).
The downside of Illustrator is that you can only load and edit one page of a PDF document at a time. Illustrator can also run into problems with embedded fonts. Its solution, however, is different from Acrobat’s response. Illustrator will replace an embedded font with a similar font. Unfortunately, the process tends to go smoothly only for letters and numbers. It goes less smoothly for punctuation marks, and very badly for special characters. Technical documents (and these documents in particular) have many special characters. I must frequently replace dozens of characters before I ever get to make the intended editorial changes to the documents. As I go through this process, I remind myself that the company pays me by the hour.
The changes, as I have indicated before, are minor. The company refined its manufacturing process and eliminated an outdated element across a wide platform of products. Due to the change, they have redefined package codes for those products. Because these are legacy documents, mostly dating 1994 to 1996, the products themselves are near the end of their lifecycle. Instead of inserting the new codes, I am changing the codes to a variable “x” so that (they hope) no future changes will need to be made. Some documents merely need a graphic (and the copyright info) updated and others require many small changes. I must, however, review each document must in detail to find these instances. The instances cannot be tracked solely through searches because many of the codes reside in graphics.
Technical Writing Jobs
This is not a job most technical writing books describe, but it is a common technical writing job. Not every job is about documenting new products or telling people how to accomplish things. Much of the work involves datasheets, specifications and reference guides. This is dull work even when you are creating the documents, and duller when you are merely updating them. This is also the sort of work that proves it is not always your writing skills that get you a job ? often it is your tools skills. Because I know how to use Acrobat, Illustrator and FrameMaker, I was a solid candidate for this job. Many of the jobs I have gotten came to me because I knew a certain set of development tools. Below is a core set of development tools every technical writer working today should know.
Adobe
- FrameMaker
- Acrobat
- Illustrator
- PhotoShop
Macromedia
- DreamWeaver
- Fireworks
- RoboHelp
Microsoft
- Office (Word, Excel, PowerPoint, Access)
- FrontPage
- Visio
- Project
