Case study - Automating HTML and PDF generation from a single source

Alation needed an efficient, automated solution to generate user-friendly PDFs from their single-source documentation.

Client
Alation
Year
Service
Documentation strategy and custom development

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

  • Sphinx
  • LaTeX
  • GitHub Actions
  • reStructuredText
  • GitHub Pages

I have the pleasure of working with David (from TechDocs Studio) on the documentation site improvements at Alation. David implemented multiple changes, contributing massively to user satisfaction. He improved site maintenance processes and provided consultations on Sphinx and reStructuredText. David’s work ethic is exemplary, keeping progress transparent and organized, which is crucial for staying on track and on budget.

Elena Barmina
Documentation Team Lead

More case studies

Creating codelabs for training internal developers

We developed a series of codelabs tailored for the internal developers of a global fashion company. Our collaboration involved defining learning paths, planning the codelabs' structure, creating engaging content, and providing sample code repositories.

Read more

From zero to developer docs

Finboot is the dynamic SaaS company behind MARCO, the enterprise-grade suite of blockchain applications and middleware solutions for value and supply chains.

Read more

Software documentation?