In recent years, companies have pushed us to work as enablers, coaching a larger number of engineers and other professionals into writing their user documentation. However, engineers adopt or develop a plethora of tools and formats to drive their work. These days, this often means having various artifacts in multiple Git repositories, including various flavors of Markdown documents, comments in source code, API references in Open API, and home-grown formats to capture technical detail such as infrastructure.

All this information is useful both to the engineers creating it and to other audiences. A specific audience may need information that is scattered across different repositories and formats. Therefore, we must consolidate that information into published documentation. We must also implement a navigation structure that makes sense to that specific audience.

At Farfetch, the solution was to convert information into intermediate DITA topics. We then published subsets of these topics in a structure suitable for each audience.

Originally published in ISTC Communicator, Winter 2025.

Attachments

Combining contributions from multiple sources

Local copy of the article as PDF.