I’m an Information Developer working in the project that has a huge library of documentation on support. Currently, I am writing 4 guides from scratch, and beside that, I have 8 or something documentation sets to maintain. Some of the guides are mine, but most of them were written by 3 or 4 other authors.
Working with a guide that is not written by you is no joke. While maintaining legacy documentation, I face countless issues regarding various aspects of document creation: from illogical structuring to outdated graphics, from missing procedures to corrupted template, from broken links to mere typos. The main difficulty I’ve encountered so far is witnessing the flaws of a document and not being able to fix them. It is quite hard to restrain from editing and proofing the wrongs I’ve spotted in all places. Oh look, that topic misses a key point. And this link is broken. And there’s an extra space. Missing key points and extra spaces in 12 docs! Isn’t that a lot?
Where to start? What to ignore? How to snooze your inner perfectionist and just focus on the requested updates?I’ve been trying to answer those questions for a long time, and that is why I decided to launch a series of articles dedicated to such problems.
I will share my experience in managing consistency, developing guidelines for legacy documentation, and much more. This article provides tips on how to deal with requests to update guides for a completely foreign product.
Dealing with Requests
Usually, I have requests to update some parts in the documents: add a note about settings or describe a new feature. Recently, I’ve received a task from my customer to update guides for one of our old products. The problem was that I had never worked with that product before. I tried to figure out how to make accurate and reachable estimates, how to get familiar with a product in a very short time, and how to provide correct information. I’ve developed a workflow on how to deal with such requests.
First of all, thorough analysis is a vital factor of updating your guides properly. But it is a time-consuming part.
- Install, administer, and use the product following the written guidelines. Perform the basic operations to get some user experience and understand the logic. Try to work with a feature to be documented and prepare questions to an SME. Probably, you’ll spot a lot of missing information in the guides. Write it down and try to ignore it for now.
- Start reading the original documentation and step into your user’s shoes. You’ll discover the level of information depth and decide on whether to keep the new information on the same level.
- Familiarize with the originals in terms of style: it will help you get the corresponding tone and wording. On your way, you may stumble upon heavy-worded combinations or odd sentence constructions. For now, just let them be; they will become good examples of how you should not write. Or on the contrary, you might find some truly inventive and efficient language patterns you’d like to follow.
- Communicate with an SME. Be prepared that the needed person might no longer work at your company, and the original documentation will be your only source of information. If the SME can be easily approached, you should retrieve as much information from them as possible. Clarify the task and discuss the potential alterations that might appear if you add a new piece. Find out whether the application contains any functionalities that should reference new information.
- When all the requirements are collected, provide estimates. Keep in mind that applying comments after the SME’s review may take more time than usual and you might need to contact the SME more often.
- Then comes the process of developing content and finalizing the document.
- Write the content keeping the existing tone and voice. Here comes the main difficulty: how not to repeat bad practices and to subtly add corrections. I try to follow common word combinations and constructions throughout all the documentation to maintain consistency but that does not mean that I’m limited to the existing patterns only. There is always space for improvement.
- When the content is written, ask your SME to review it, and then apply the comments as required. Perform usability testing of your documents, check the links, fix the layout, and update TOC. Finalize the document and publish it.
Here we can make several conclusions about updating the legacy documentation:
- If you are not familiar with the product, the analysis stage is crucial.
- An SME is your main source of information.
- Stay focused on the current task and do not let your attention wander on the document’s imperfections. If you spot a bug, make a note about it, and then proceed further. Try not to dwell upon it in the process of creating new content.
But don’t forget about the final step: compile a list of imperfections within the documentation. It should include all the wrongs you’ve encountered along the way: unclear document structure; long or illogically separated chapters; missing points that definitely would be important or helpful for users; corrupted or visually displeasing template; broken links. Even extra spaces! Gather everything that makes your experience of using the document dull, difficult, or unpleasant. Stay tuned for the second part of the series to discover what to do with this list next.