By Soumya. P. Sadanandan

Startups and smaller development units most often cannot afford to keep people dedicated to documentation. The similar situation can be seen in some of the not so profit-making development units in larger organizations as well. In these organizations or development units, the software developers perform the role of a technical communicator as well. This write-up is about such a role in such a unit.

Your product is completed and is ready for release, and you are thinking about product documentation. Ideally, you should have planned and started for documentation at a much early stage in the Software Development Life Cycle (SDLC). But in the real world, teams rarely work on product documentation before the Release phase. Let us assume that your company adopts online documentation.

If your team has budget constraints and cannot allow affording an independent technical writer, the project manager (PM) allocates a relatively work-free developer to the role of a technical writer. In most cases, this developer is a fresher, who does not have a complete real-life experience in the SDLC.

The person allocated starts by taking the Table of Contents (TOC) provided by PM, and collating information that covers the TOC. If the team already has some offline documents (traditional documentation done in Microsoft Word), then the online documentation will be more or less a copy-paste of that.

Guidelines

In this scenario, you don’t have enough time to completely train the developer and make his competency at par with a technical writer. But based on our experience with such teams, we have created some guidelines which will reduce the burden on the editorial team. These solutions begin at an early stage of documentation and not at the Editorial Review phase.

Head and Tail

Where should the documentation start and end? Request the developer to give you a complete Information Architecture (IA). In this way, both parties get a clear idea about how the information is going to be structured. Once the skeleton is ready, it is easier to add flesh to it.

Fonts and Headings

Don’t give control of formatting to writers. There are chances that the developer will play around with font size, font color, and heading templates resulting in a messy structure. Use a good, user friendly authoring tool that automatically handles the formatting aspects, so that writer has control only over the content.

Content Structure

For online documentation, it is best to stick to the Darwin Information Typing Architecture (DITA) principles. Even if your authoring tool doesn’t support DITA, you can learn and implement its principles. At a high level, a DITA topic should have title, pre-requisites, procedure, result, and post-requisites. You can use DITA to enforce any structure you want.

Sharing Editorial Review

For ease, editors copy-paste content to MS Word, enable ‘track changes’, review it and share it with the developer. The expectation from the developer here is to read through the document, understand the mistake, and learn from that. But what happens is that the developer “accepts all changes” in the MS Word and copy paste the content back into the authoring tool. Because the developer hasn’t learned anything from this review, the mistakes continue. To prevent this situation, the editor should take the first two topics and share the general feedback such as use active voice, add a space after every comma.

Conclusion

Wherever developers take up the role of a technical writer, it is imperative to train them properly for achieving the desired document quality. In our organization, we have selected a champion from each product team, who is trained in all aspects of technical writing. The champion owns the writing or training a new member, and performs the first level of editorial review. This ensures that the editorial team spends less time in training and reviewing documents.

About the Author

Soumya. P. Sadanandan works as an Assistant Consultant at TCS Kochi. She has around 10 years of experience in the IT domain. She started her career as a Lotus Notes Developer and later switched to User Assistance domain. Currently, she is part of the User Assistance CoE in TCS, which focuses on developing assistance for TCS Products.