The challenge

Alation was already producing HTML documentation alongside a single 4000-page PDF. However, the PDF format presented challenges: users struggled to navigate such a large document to find specific information, and managing updates across both the HTML and PDF formats was time-consuming. They needed an automated solution to streamline the generation of chapter-based PDFs from the same source as the HTML, making it easier for users to access specific sections and improving overall navigation.

Solution: Single-source, multi-format automation

We adopted a Docs As Code strategy to automate the generation of:

• HTML and PDF outputs: Both formats are produced automatically from the same documentation source, ensuring consistency across outputs.
• Chapter-based PDFs: Users can now download individual sections based on their needs, reducing download time and improving document navigation.

Tools and automation

Using Sphinx for documentation management and LaTeX for PDF formatting, we automated the process with GitHub Actions. This setup allows Alation's team to:

• Automatically generate outputs: Every update to the documentation can triggers HTML and PDF versions, removing the need for manual intervention.
• Ensure consistency: Single-source content ensures both formats—HTML and PDF—are always up to date with the latest changes.

Results and impact

• Efficiency improvement: PDF build times were reduced by 50%, thanks to compiling smaller chapters instead of the entire document at once.
• User satisfaction: Qualitative feedback indicated that users found the ability to download individual chapters more convenient and the overall experience more accessible.
• Streamlined maintenance: While the workflow doesn't eliminate review tasks, it significantly expedites the process, with build times for individual PDF chapters dropping by 95% compared to building the full PDF.

Tech stack