The wild west of polyglot docs sites

The multi-language documentation site landscape is a challenging frontier in technical writing, fraught with quirks and complexities. To produce documentation for a project that offers libraries in N distinct programming languages, you often need to contend with N or N+1 separate documentation generators. Each language has its own API reference generator, and despite libraries being loosely coupled, the documentation site frequently requires tighter cohesion.

The goal is to harmonize the outputs from disparate generators into a unified experience. Unfortunately, there's no widely-accepted term for this type of documentation setup. For now, let's refer to it as a polyglot docs site.

Polyglot docs sites feel like an uncharted territory in technical writing, teeming with challenges. In terms of top-down strategy, there are only two viable approaches. Both approaches have their own set of major issues.

The first approach involves parsing each API reference generator's output and transforming it into markup compatible with your main documentation generator. For instance, during my time at my first job, we took Doxygen HTML as input and used XSLT to convert it into simpler HTML fragments. Then, we incorporated the raw directive to embed these fragments into our Sphinx site.

One drawback of this transformation strategy is the loss of expertise from the API reference generators. Tools like Doxygen, rustdoc, and javadoc understand the nuances of their respective languages better than most. Over-customizing the output with a transformation tool risks stripping out essential user information. Transformation also goes against the grain of the ecosystem.

Users are already familiar with the UI of the native API reference generators. Introducing a new, unfamiliar UI can be a deterrent. Another example of this approach is Breathe. Breathe parses Doxygen XML and makes it available as input for Sphinx builds, generating API references that Sphinx can understand. However, there are several drawbacks to this approach.

Firstly, it can be a significant bottleneck in your documentation build process. Secondly, the additional glue code can lead to silent failures. Lastly, it provides too much flexibility, with contributors sometimes organizing the doxygenclass directives in ways that make managing the final output difficult.

The second strategy is to rely on the expertise of the API reference generators and publish their output as-is. Pigweed.dev does this, with separate documentation sites for C/C++ (Doxygen), Rust (rustdoc), and everything else (Sphinx). While this creates an architecture resembling a turducken, it has its own set of problems. The subsites look different from each other, and it's challenging to navigate between them or link between them.

To address these issues, pigweed.dev introduced a universal header with a consistent UI for accessing the in-site search. The search now opens as a modal, providing results as you type, which improves the overall user experience.