Documentation Process

After joining the company, my first priority was to create a documentation workflow. But since I joined the company in the middle of a release, I had to continue with whatever workflow or no workflow was present. The doc tasks were sent by mail and it was tough to keep track of  all the doc tasks. Eventually, I did miss out a few of the doc tasks as they got buried in the email avalanche. So in my first ever product release in my new company, I had learned the importance of having a documentation process.

In this blog I am going write about the documentation process which I have implemented in my company. Anybody can refer this process and modify as per their requirement to use it their company.

Since I can’t publicly use the name of the product I am working on, I will use a dummy product that goes with the name JarvisBootStrap v2.0. I have written the process in Q&A format to simplify things.

The documentation tasks are split into two categories:

Doc requests related to current release

  • Product features
  • Enhancements

Miscellaneous doc requests

  • Doc bugs
  • Other doc tasks

Following is the documentation process.

Q. What are the different category of documents for JarvisBootStrap?

Let’s take a look at  the documentation suite we have in our company.

  • Release Notes
  • User Guide
  • Configuration Guide
  • Product Factsheet

Q. What kind of information should the developers share when they select the Documentation Impact checkbox in Jira?

For any new feature or any enhancement/bug, if there is an impact on the UI, the developers should mention which screen is changed. Also include if the JarvisBootStrap.xml file has been impacted.

For any new feature or any enhancement/bug, if there is a change which is not directly visible by the user, the developers should mention what has changed.

While working on a user story, if there are any suggestions/comments related to documentation, then all the comments/suggestions should be added to the user story for documentation in Jira.

Let’s take a look at the documentation task categories in detail.

Documentation requests related to the current product release


Following is the proposed documentation process.

  1. Product owner will create a user story for documentation in each Epic in the Product project.
  2. Product owner will also add the Acceptance Criteria for documentation.
  3. The user story for documentation will have zero story points so that the burndown charts are not affected.
  4. Each user story for documentation will have three tasks, Information gathering, Writing, and Review, which will be created by technical writer.
  5. After the writing task is completed, the documents will be shared with the QA team for technical review.
  6. The user stories for documentation may have a lag of one sprint.

Q. For which documentation requests should a user story for documentation be created?

For any requests related to product features/enhancement, in the current release, which may have a documentation impact, a user story for documentation should be created.

Q. Why not create tasks in Documentation project for doc features/enhancements?

Any documentation requests related to the current release should be created in the Product project to track them easily in scrums. The Documentation project in Jira is for tracking doc bugs which are not related to the scrum.

Q. How will developers, QEs, SMEs share information, related to a feature, with the technical writer?

If there is any information, related to a feature/enhancement, that needs to be communicated to the technical writer, a comment should be added in Jira in user story for documentation.

Miscellaneous documentation requests  


Q. What is the need for documentation project?

Currently, many doc requests come through email. When an email for documentation request is sent, it is tough to track the progress of the request. Also there are high chances of the documentation request getting buried under the email avalanche.

Q. Who has access to the documentation project?

All team members.

Q. What type of tasks can be created in documentation project?

For any requests related to creating/updating a page on Confluence or doc bug, a Jira task should be created in the Documentation project.

Q. How to go about it?

If you have any documentation requests which are not related to the current release, a Jira task in the documentation project should be created.

After creating a documentation task, an email should be sent to all the stakeholders about the Jira task. If anyone has any suggestions/comments for the documentation request, they can directly add a comment in the Jira task.

Documentation review process

Q. When does the review process start?

After the Writing task is completed by the technical writer, the documents will shared by the technical writer with the stakeholders.

Q. How will the documents be shared?

The documents will be uploaded to Documentation Review task for the respective user story for documentation in Jira. The documents will be uploaded in either PDF or .docx format.

Q. Who will review the documents?

Documentation review will be in two stages. In the first stage, the documents will be reviewed by the QA and in the second stage, the documents will be reviewed by the Product Owner.

Q. Where to add review comments/suggestions?

We have shortlisted two methods to share review comments/suggestions.

Adding comments/suggestions in Jira – When the suggestions/comments are added in Jira, all stakeholders can view all the comments. It is easier to track all the suggestions/comments when comments are added in Jira. The Jira comments will also be useful for future references.

Adding comments/suggestions directly in document – As a reviewer, you may add your comments/suggestions as annotations in the document being reviewed. The document with review comments can then be attached in the Jira comments.

Q. Which method to use for sharing comments/suggestions?

We have decided to experiment with the second method, adding comments/suggestions directly in document, for sharing comments/suggestions. If this method is viable and useful we will continue using this method else we will shift to the other option. If there is a change in the method, it will be communicated at all levels.


The Startup

Working as a lone writer has its pros and cons. It also has a lot of challenges. After a decade of technical writing and working in some of the top notch companies, I decided to deep dive and take up a challenge with a startup.
Leaving Red Hat was very tough. I had a pleasure to work with some of the most talented people I have ever met. Red Hatters are some of the craziest, most passionate people on the surface of Earth. Working with Red Hat gave me an opportunity to work in the world of open source. Red Hat taught me how to explore the sea of unlimited information, learn new tools and formats, and so many other things. This gave me the confidence of taking up the challenge with a startup. Life@RedHat was really awesome!!

Initial days

I joined my new company six months back, in the month of September 2015. In the team of 50+ which includes Devs, QEs, and Delivery, here I was standing alone, representing my passion – Technical Writing. People had weird ideas about technical writer and writing. They didn’t give much importance to the documentation. According to them, documentation was a job for the losers. People who are unsuccessful as Devs, QEs, and in other fields, take up tech writing for survival. Now this was a challenge I had; to change their mindset. I had to educate people about technical writing, technical writers aren’t losers but biggest contributors to the success of a product. Without good documentation, product has no value in the market. I am glad that I have almost changed that perception now. Though there are still some who under rate writers but it won’t be long before I win over them and hoist the writers flag high.
Another challenge, the biggest of all, was the condition of product documentation. The product documentation was in MS Word! Yes you read it correctly. Microsoft Word! An outdated, stone age era tool which is hardly (just being nice to Word :)) used in the new world of tech writing. The previous writer had done a good job but there were still lot of areas for improvement. The writing style, information flow, the processes were all in dire straits. With all these issues still in the field, I managed to get out two major and one minor releases with the existing tool chain. Although the quality of the documentation was not up to the standards, it was still like winning a small battle in a big war!

Getting started

After joining, my top most priority was to get acquainted with the product and start documenting the new features/enhancements for the upcoming release. Along with new features/enhancements, another task was to set documentation process. With no process set for documentation, I used to get tasks and requests through mails which was a big hassle to track.
I will explain the doc process in short over here. Since we are using Jira, I created a project in Jira for documentation. All the doc requests which are not related to the current release go in the documentation project. Any one from the product team can create an issue in this project. For tasks related to the current release, in every Jira epic, a story for documentation is created. Each doc story has three tasks; Information Gathering, Writing, and Review.
For those of you who are unfamiliar with the agile/Jira workflow, I will try to explain the process in brief. In agile workflow, an epic is created in Jira. Each epic can have multiple stories. Stories are usually product features which need to be developed. Each story can have multiple tasks and in turn multiple sub tasks. The workflow may be different in different organizations.
Let’s take an example. User Administration can be called an epic. In User Administration there can be various features like adding a user, deleting a user, modifying a user and so on. These are all stories under the epic User Administration. Similarly, User Administration documentation can also be added as a story in the epic to track the related documentation tasks.

The future – roadmap to glory

After being six months at the helm, I finally have a roadmap to take the docs to glory. Recently, I received the license for a new tool chain – Madcap Flare. I am finally moving away from Word!! feels good. I have never used Flare but from what I hear, it’s not that bad. So here is the roadmap for glory which I have proposed to the management.
To understand what needs to be changed/updated in the docs, a documentation audit is planned. A documentation audit is a review of the entire documentation. The aim of the audit is to improve the documentation by making the guides easier to use, more user-friendly, and more customer-centric. The docs will be reviewed by all the stakeholders and the findings of the doc audit will be added to the doc project in Jira.
Simultaneously, docs will be migrated to the new tool – Flare. Migrating to a new toolchain is never an easy job. Once you import the content in the new tool, the fonts, style, everything goes for a toss. Keeping this in mind, two versions for docs will be maintained. Version 1 will be the same old MS Word docs, which will continue to exist for a couple of releases. The MS Word branch will be maintained and updated for the new features for the upcoming release. The new features will also be copied in the Flare branch, to keep it updated. The same old style MS Word docs will be released for next version of the product.
Version 2 will be the migrated content in the new tool – Flare. The documents in Flare, will be restructured and updated as per the findings of the documentation audit. Once the docs in Flare are structured and are good to go, the MS Word docs will cease to exist. Just like Simon Phoenix, the criminal in Demolition Man, the Word docs will be cryogenically frozen in time. Hope the Word docs don’t resurrect in future like Simon Phoenix! 🙂