Hugging Face admits its Transformers docs are a 'mess' and rebuilds them

Hugging Face is undertaking a full redesign of its Transformers documentation after acknowledging the current experience has become disjointed and difficult to navigate. The core problem is that content was added incrementally for nearly three years without reconsidering how the audience or the library itself has evolved. What started as a resource for machine learning engineers and researchers now serves a much broader group of developers who are building products with AI, not just tinkering with models.

Clement Delangue, Hugging Face’s CEO, put the shift in perspective with a prediction back in March 2023: companies that build and train their own models internally will build ‘100x better’ products and capture long-term differentiation. That sentiment frames the redesign’s primary goal. The new documentation will be code-first and solution-oriented, tightly coupling code examples with beginner-friendly explanations of machine learning concepts. The idea is simple: a code snippet without context is useless to someone unfamiliar with AI, and that’s exactly the developer the docs now need to serve.

The redesign also abandons a rigid adherence to Diátaxis, the documentation framework Hugging Face adopted in 2021. The author admits using the system as a plan rather than a guide, forcing content into four predefined categories even when it didn’t naturally fit. That structural rigidity is being replaced with flexibility, allowing organic documentation structures to emerge and scale naturally. As the article puts it, ‘It’s okay if the structure is complex, but it’s not okay if it’s complex and not easy to find your way around.’

The final push for a redesign comes from what the author calls the documentation’s ‘tree rings’ — three distinct eras of content: multimodal models, large language models, and the current optimization era focused on quantization, FlashAttention, LoRA, and helping the GPU-poor. Each era layered new content on top of the old, unbalancing the whole. The redesign aims to integrate rather than amend, making new content feel native to the documentation instead of bolted on. Whether the new structure actually solves the discoverability problem remains to be seen. Documentation overhauls are easy to announce and hard to execute well, especially for a library as sprawling as Transformers.