Working with Legacy Documentation. Part 2

Following my previous publication dedicated to managing legacy documentation, in particular, to dealing with requests for updating, today’s post touches the hardships of style.

Like a fingerprint, our writing style is unique and individual, as it reflects the patterns of our thinking. Word choice, sentence structure, sentence order, text tone – every aspect of your writing is filled with your presence, and “author’s presence” is a thing not required in information development. We have to shun picturesqueness and verbosity, and focus on the three C’s (clarity, conciseness, and consistency), throwing away the rest of alphabet. Easier said than done, especially if you tend to write like Galsworthy.

What all of this has to do with legacy documentation? The answer is simple: when dealing with it, you have to adjust. How do you decide, whether to follow or to fight? What do you do when you are forced to follow foreign manner?

Challenge

When I started developing documentation for my customer, I learned that I had 4 predecessors. Their writing styles are quite visible: one can distinguish one author’s manual from another’s. Of course, I assume my docs also have their peculiarities, but the ultimate goal is to make MY document sound and look as if it was MY CUSTOMER’S. To achieve that, one would usually use the style guide.

But here comes the challenge: there was no style guide.

When I got my first guide done, the customer sent me a review with numerous comments like “Please, don’t use this word, use that word instead”, “Please, rewrite this in a way it is in the other guide,” and so on. I was fairly surprised because there were no rules that I had been informed of beforehand. How could I know? But that was something I had to cope with, and the decision was made: If there is no style guide, I’ll create one. At least, for myself.

Solution

My strategy was to investigate the issues with the style and create a Style Reference List. The workflow I devised consisted of several steps.

  • Check the Microsoft Manual of Style compliance. 

I analyzed the existing documentation for inappropriate patterns that should be avoided. Several older documentation sets violated the standards of the Microsoft Manual of Style. There were cases when procedures had countless steps, or unnecessary screenshots, or specialized language. Also, I spotted issues with formatting: bold, italic – all mixed up. All those problems should be recognized and reviewed.

  • Review the corrections made by the customer. 

In my case, some of them were quite reasonable, but a couple of comments also ran contrary to the MMoS. Several suggestions were either techy, or wordy, so they couldn’t be applied. Therefore, the reasons for negotiating the customer’s changes and not accepting them right away had to be justified. That required a lot of persuasive skills considering that the reviewers were native speakers. When all the problematic cases were discussed, the final variant of each case was agreed upon.

  • Gather customer’s preferences. 

Find out about other features that the customer would like to have in their documentation but that were not voiced. For example, icons, and screenshots, and workflow diagrams were very welcome, and that answered my question about the abundance of graphics in older versions.

  • Compile a Style Reference List. 

I made a list of documentation requirements that consisted of valuable existing practices, customer’s suggestions that were accepted, and my corrections to the current patterns. I still maintain that list, as new cases occasionally appear and require attention.

Final Thoughts

These steps are the first ones I took on my long road to a full-fledged style guide. Still, many issues that might cause troubles while writing are not covered, but certainly, the Style Reference List is a source to refer to, when I’m in doubt. For now, it’s a foundation that can grow into profound writing guidelines that would help others in their quest to find balance between what the customer wants and what the user needs, what informs and what illustrates, what is beautiful and what is useful.

I would be grateful to hear your ways to tend the absence of style guide, so feel free to comment!

Also, if you haven’t read about my struggles with the requests to update the legacy documentation, check it out here.

Advertisements

One thought on “Working with Legacy Documentation. Part 2

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s