Optimizing Clinical Trial Documentation: Boosting Efficiency & Cutting Costs with Docs-as-Code
About the Client
Our client is a leading imaging informatics company based in the USA, specializing in comprehensive tissue-to-human imaging, analysis, and data management solutions. They serve pharmaceutical and biotech clients across all stages of the drug development pipeline.
The client supports its operations with two flagship platforms:
A multi-modality post-processing suite for imaging data (e.g., SPECT, CT, PET, MR).
A web-based platform for managing and reporting medical imaging data and metadata.
The Challenges
We encountered substantial challenges due to an inefficient and sluggish technical documentation process. This often resulted in outdated materials, a poorly designed user manual site, and increased customer frustration.
Inefficient Authoring Processes
The processes and tools used to create and maintain user manuals significantly hindered timely publication. Microsoft Word files were repeatedly exchanged, resulting in numerous iterations and extensive feedback loops. A clutter of documents was created, with inconsistent file names, which caused confusion about outdated and current feedback.
Apart from authoring the content, writers had to apply a consistent formatting style to the MS Word files. This task alone could add an additional 6-8 hours of work per documentation set, delaying the start of the final review process.
Time-consuming Content Publishing
Our client publishes their user documentation to both a public website and a downloadable PDF. Since single-sourcing was not considered during the documentation process, the content had to be converted twice.
This process created a bottleneck for document maintenance, as even a small change required repeating the entire conversion and upload process. Additionally, publishing changes to the content depended on the software build pipelines, further slowing down the update process.
Poor Scalability and Version Control
As new software versions were released, the volume of associated documentation grew significantly. Each set of documents had its own versioning system, which became increasingly complex and challenging to manage using traditional tools. This made it difficult to keep track of the latest versions and ensure consistency across the documentation.
Siloed Processes Between Developers and Writers
Despite being part of the same project, developers and writers worked independently, using siloed processes to complete their tasks. This delayed the documentation process, as it was not included as part of the software development cycle.
The Solution
Our client needed a scalable and efficient solution to keep their projects on track. To address this, we implemented new tools and processes to simplify and streamline the workflow for creating, updating, publishing, and maintaining the company’s user documentation.
The Docs-As-Code Approach
Docs-as-code treats documentation as an essential part of the development process, as important as the code itself. Teams use the same tools and processes they use for software development to manage and maintain their documentation, ensuring that the documentation stays current and accurate as the software code evolves.
After thorough research and assessment, we developed the following streamlined process:
The content is written in MarkDown, using text editors such as Visual Code Studio or Atom.
The MarkDown files are uploaded to a version control system, such as GitLab or GitHub.
Technical and editorial reviews are performed via pull requests, which requires a series of validations before they can be merged and built.The HTML output is built via Jekyll, an open-source static site generator.
We collaborate closely with the UX team to adapt Jekyll's community-maintained templates, customizing the user documentation site's design and styling to match the products' branding and visual identity.CI/CD tools, such as Jenkins and GitLab are used to automate the build, test, and deploy the documentation.
The new publication process is completed in just minutes, significantly reducing the time and effort required. With no need for documentation formatting or transcription, content can be published seamlessly across multiple targets.
Content Single-Sourcing
We use Prince13, an application that converts HTML documents into PDF files by applying CSS. Content is written once in Markdown and reused to render both an online and an offline source of content.
Documentation Versioning
In software development, different code versions and branches may exist simultaneously. In the same way, we perform documentation versioning and branching to generate documentation for specific code versions or branches.
This allows users to access the documentation corresponding to their particular version, reducing confusion and providing clarity.
Efficient Bug Fixes and Updates
Storing the documentation in a separate Git repository from the main product code enables faster identification and resolution of documentation issues. The documentation build cycles are independent of the code release schedule, which allows for more agile updates to the documentation.
Agile Documentation
Agile software development has transformed the landscape of technical documentation. We adopted the principles of the agile methodology to produce documentation that evolves in sync with the product. Technical writers work in sprints, aligning their efforts with the developers' pace. This dynamic approach allows for timely updates and ensures that the documentation remains relevant and up-to-date throughout the development process.
The Outcome
After the implementation of the docs-as-code approach, we presented highly scalable, responsive, and completely upgraded, web-based user documentation.
Apart from the operational benefits, the new documentation approach reduced costs by leveraging state-of-the-art, open-source software to improve the documentation processes.
We also reduced time and effort by including the technical documentation work as part of the agile development cycle.
