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
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.
- Product owner will create a user story for documentation in each Epic in the Product project.
- Product owner will also add the Acceptance Criteria for documentation.
- The user story for documentation will have zero story points so that the burndown charts are not affected.
- Each user story for documentation will have three tasks, Information gathering, Writing, and Review, which will be created by technical writer.
- After the writing task is completed, the documents will be shared with the QA team for technical review.
- 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.