F-Talk: Integrated API Documentation at Scale

As part of the Farfetch F-Tech Talks, I reported on the tools and processes used at Farfetch to create and publish API documentation, and how they evolved over time.

The API documentation combines traditional DITA topics with API references generated automatically through Open API specifications. The generation of API references was actually done three times, as the documentation source moved from C# comments to Open API specifications.

Talk: Integrated API Documentation at Scale (video, 48:00)


Technical Writing at FARFETCH has the challenge to explain a business platform continuously evolved by thousands of people and used by hundreds of partners. This presentation will show the technical processes used to keep API documentation up-to-date and seamlessly integrated with documentation written more traditionally. These processes have evolved with company needs and currently support documentation within FARFETCH and with selected partners.


Joaquim graduated in Computer Science at Universidade Nova de Lisboa in 1988, then post-graduated in Management (PAGE) at Universidade Católica de Lisboa in 2001. He worked as programmer, systems administrator, trainer, consultant, and University researcher.

In 1997 Joaquim embraced a career at Altitude Software as technical writer, trainer, writing tool developer, translation manager, and team manager. Joaquim joined Farfetch in 2016 to lead technical writing and publication tools.

Joaquim hired and trained dozens of technical writers, inovated with writing patterns, business comics, business domain models, and agile methods.

Member of ACM, IEEE, APCOMTEC, and ISTC, Joaquim started in 2013 the informal group of technical writers at Lisbon and collaborated in the creation of the post-graduate course on Technical Communication at ISCAP (Porto). Joaquim has presented his work both in academic conferences and in communities of practice.