Brevity may be the soul of wit, but clarity is king
Along with creating useful and engaging features, I wrote long-form content such as change comms and documentation to empower users and drive engagement with what we’d built.
On this page:
• Documentation – Fields and Permissions sections in Jira Admin
• Change comms – Improvements to Fields
• Documentation – Program board
Documentation – Fields and Permissions in Jira Admin
Based on project needs, as well as perceived customer service support (CSS) cost reductions, I led a project to rewrite the Jira Admin documentation. This work focused on improving the readability of the organically-grown content, alignment with the strategic positioning of the doc sets, improving the quality of material on which our AI agent was trained, and migrating old content to a topic-based authoring system.
To do this, I:
- worked with other crafts and disciplines to define positive outcomes of work
- audited existing documentation content, identifying content that was out of date or in need of rewrites
- redesigned the IA to make navigating the documentation more intuitive
- wrote new content that matched these strategic initiatives
As a result:
- these new docs have a combined Flesch-Kinkaid score of 70
- 32,000 words removed, creating clearer and easier to understand documentation and increased user understanding of the power of Jira
- an estimated $600k reduction in customer support costs
Change comms – Improvements to Fields
As part of a larger change to how Fields — a core function of Jira — operate, I created external facing communication that disclosed the upcoming changes
To do this, I:
- explained how the new experience would conceptually differ in a way that made sense to and addressed the concerns of the Admin audience
- disclosed the right amount of information at different stages of the development cycle, offering more details as the release grew closer
- informed users of upcoming procedural changes they’d need to make to prepare for this change, including API changes
- encouraged feedback and further user input through early access and testing
This work was successful in that:
- the reception on all public-facing pieces was largely positive
- users asked clarifying questions which opened the door for further education and understanding
- we identified areas of concern which impacted or were added to decisions about how to build this new feature
Note: the files below were posted by the feature lead, but ghostwritten by yours truly.
Documentation – Program board
Plans released a feature called the Program Board which aligns to the concept of PI Planning in SAFe methodolgy. It’s designed to help planners plan work for the next quarter (approx. 3 months). As part of my role on this team, I wrote the documentation for this new feature.
To create the documentation, I:
- identified and prioritized information to include based on our audience
- researched specific functionalities and limitations with the team
- wrote, proofed, then sparred the content
- uploaded it into our content management system and formatted it to meet our content standards
As a result, the documentation:
- introduces the concept to users
- explains how it works, specific functionalities planners would find helpful, and how to achieve these outcomes
- is easy to read and accessible to a wide audience
This work was successful because:
- Flesch-Kincaid scores ranged between 63 and 73 (approximately a year 7 reading level)
- users gave it a 55% helpfulness score over a six month period (average for Jira docs was 25% — it’s a tough crowd)