Moving release notes from PDF to HTML
2021-2024
Context
Prior to 2021, TraceLink’s release notes were exclusively distributed via PDF and provided to customers in the support portal only, completely separate from the documentation. As a company that provides software to customers in a highly regulated industry which must comply with Good X Practices (GXP) and participate in government audits, our release notes are incredibly important, visible documents and require careful thought, as well as executive approval, to change significantly.
As we began releasing apps on the new platform, they were each released independently of each other instead of as a single release for the entire platform, like the legacy platform did. The development and release cycle for apps on the new platform was also much more frequent. The Technical Communications team needed to scale to keep up with the release notes on the new platform, which we could not do by continuing with the same processes for the PDF release notes.
Research and implementation
By leveraging competitive analyses that demonstrated large platform companies (including those in supply chain industries like SAP) all provided HTML release notes integrated with their documentation, I created a prototype and convinced stakeholders to move to this model for all apps on the new platform. However, we still had to provide a PDF version, which brings its own complications to the document design.
As with the overall documentation strategy, I defined the IA as well as the styles and standards, created templates, trained the writers, and led the implementation. After implementation, I developed and delivered training for the R&D and Services departments to educate them on the new format.
I also currently meet with customers who have questions about the release notes strategy and continually make updates based on their feedback.
Results
In addition to providing a better experience for our users, the new release notes process streamlined the amount of work required by reducing content duplication and leveraging single sourcing much better than the siloed PDF strategy. It allowed the Technical Communications team to scale by providing quality documentation for the many additional apps TraceLink has released on the new platform.
Skills
Leadership, training, project management, competitive analysis, proposal presentation, CSS and HTML coding, release notes writing, IA, reviewing, iterating based on widely varied feedback
Tools
MadCap Flare, Brackets, Confluence, Jira, Excel, PowerPoint