Most writers will agree that getting the reviews done for our content is one of the toughest challenges in our jobs. It becomes even more challenging if you conduct 15 reviews for every feature that you document. The challenge is not only to get the reviews done, but also tracking the status and raising any escalations at the right time. Hence we decided to track all our reviews through JIRA as that would help us address these challenges.
In early 2019, I was tasked with running a pilot and educate everyone about the new process. On day 1, I realized that it’s atrocious to ask the writers to create 18 JIRA tasks for every feature they document. And if I ask them to do so, I’ll be outcasted from the lunch table!
I came up with the following incredibly easy solution that proved to be immensely helpful:
- Gathered all details that are required to create and track the JIRA tasks.
- Created an Excel sheet with the required JIRA fields, each row in the sheet depicting a JIRA task to be created.
- Created a configuration file (JSON) for mapping different fields of the Excel sheet to the JIRA fields.
- Created rich filters and dashboards in JIRA to track the progress of each task. What the writers need to do:
- Download the Excel template and configuration files from a shared location. • Enter 3 inputs in the Excel sheet: the feature they are working on, the name of the product, and their JIRA login ID.
- Save the Excel sheet in CSV format.
- Import the CSV and the configuration files to JIRA.
Fig 1: A glimpse of the Excel template. The three required inputs are highlighted:
Importing the files will create one JIRA story containing 17 tasks with appropriate labels and other details, along with a predefined estimate for each task. The tasks are automatically assigned to the writer importing the CSV (can also be assigned to others by entering their JIRA login ID).
What the leaders and managers do:
- Apply filters, view, and/or download status of the review tasks on the JIRA dashboard. • Raise any pending review task as risk or blocker for the release. The release does not happen unless all reviews are done.
Fig 2: A glimpse of the dashboard:
After a successful pilot, we rolled it out to other product teams as well. Now I maintain several JIRA dashboards, making me the “JIRA guy” of the team!
A year later, I got another opportunity to plan and automate a process. In April 2020, I was tasked to plan, estimate, and lead the efforts to completely restructure 8 documentation spaces. Along with a complete overhaul of the content and structure, we also had to verify each outgoing link, and create a manageable library of those links in our Confluence spaces. It was a humongous effort, and a part
of me screamed inside in horror even from the thought of having to check 100s of links and adding each link as a “multiexcerpt” macro. I definitely did not want my team to go through that ordeal. To address this challenge, I came up with the following process:
- Found a quick way to identify outgoing links in our documentation spaces: • Export the entire documentation space in HTML format.
- Edit the HTML file and perform a “search and replace” operation.
This identifies the required links and append markers.
- Copy the marked links.
- After I have the list of the links, I parse them in an Excel book.
The Excel book had the following sheets:
- All links: I paste the list of links there without any processing. This is for backup and record purpose only.
- Preparing the links: I copy and paste the links from the All links sheet. As soon as I paste the links, this sheet automatically breaks down the links and generates the following components:
o Confluence space key
o Link text for the hyperlink
o The URL of the target topic
o Link to be created (<spacekey>:Topic title)
o Multiexcerpt name for adding to confluence
It also checks for any duplicate values.
- Multiexcerpt code generator: From the previous sheet, I copy the values in the link text, link, and multiexcerpt name columns and paste them in this sheet. This sheet automatically generates the XML code that I can directly paste in the Code view of my confluence topic. Voila! All the multiexcerpts are created.
To add more functionalities, I created two additional sheets in the Excel book: • URL extractor: One prerequisite of the Excel book is that I must paste the links in URL format and not as hyperlink. However, if you only have the hyperlinks, fret not, I have you covered! Just paste your hyperlinks in this sheet and it’ll extract the URLs from the hyperlinks and will list those for you.
- Broken link finder: As the name suggests, this sheet checks your list of links and finds the broken ones. Since we did not have much use of this sheet, I did not fix all issues and it still remains experimental till date.
Both these methods proved to be tremendously helpful for me and my team, and the other teams in the organization have also benefitted from them. I hope it’ll also help others in the community to look beyond our daily assignments, look at the bigger picture, and conquer the challenges together.