We caught most of the errors during earlier edits, but the point of this pass is to ensure that the documents are ready for publication. The documents we are working on are not meant for the public, so they do not have to be flashy (and they aren’t) but they will be read by a key client who will be developing tools based on our product. That client must have documentation that works for them, and that means it needs to be clearly written and cleanly presented.

There are currently three of us working on the documents. Each of us lives and works in a different city. One person is a regular employee (which means she is in charge) and the other is a contractor who has some time to help get this document out. We communicate through e-mails and phone conversations. We track our project using an Excel spreadsheet that resides on out Documentum server.

Unfortunately, ours is not the only project tracked by this spreadsheet. More than once, I have spent valuable time fixing the damage done to the spreadsheet by the anonymous people who work on related projects. I cannot really blame the other people. Excel is a Microsoft product. With Microsoft, you must expect and even plan for errors.

Working with people across long distances is part of doing business these days. Both of my editing partners live in the United States, which is where I live, but I have also worked with SMEs across Asia. At other companies, I have worked with people in Germany, Ireland, Australia, Canada and Scandinavia. Sometimes the distance is smaller. This company has another division just ten miles away.

I only work with one other person who is also on site. There are four other people around who perform similar functions, but we have only a passing acquaintance. Most of the people near me are on a completely different project and work for a different business group.

One of the keys to working with people across distances, especially as a writer, is patience. In many cases, you will not get the answer you want when you want it, especially is you are separated from the other person by several time zones. The SMEs in Asia are just showing up to work as I am leaving, and I work late. You get used to asking a question and then moving on — finding other things to do until the issue is resolved.

In many cases, by the time the answer comes back, you have to check your notes just to remember what you were asking about in the first place. This can be a painful process if you do not keep good records of what you are doing. For this reason, I prefer email to voicemail. It is difficult to remember exactly what you said, but easier to bring up something you wrote. Whatever your method, always keep some sort of record of who you have requested things from, and exactly what you requested. It is also good to have a plan for how long you will wait before you ask again.

The main point to remember when working within a group that does not share a location is that the entire group is dealing with the same problems you are dealing with. While you are waiting for one person to answer a question, they are waiting on another person. Everyone is in the same boat, even if their part of the boat is in a different city or country. Sometimes you need to be proactive. You might need to set up a teleconference to hammer things out, even if it means staying three hours late or coming in three hours early. You might need to guess about an answer and come back to it later. Whatever the problem, you must find a way to do your job. That is why they pay you so much money.

Hire John Hewitt - Writing Content and Web Consulting

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.

Hire John Hewitt - Writing Content and Web Consulting