Model docs design

@stevhliu|Feb 20, 2025 (3d ago)22 views

The next milestone in the Transformers redesign is to refresh and standardize the model docs.

As our audience shifts from researchers to developers, users are more interested in figuring out how to use a model compared to the underlying research and technical details.

And with models like GPT becoming a household name, good model docs - some of the most popular models have thousands of pageviews every month - are a very important resource for developers.

Initial design

Traditionally, the model docs are loosely formatted and may vary from page to page.

Llama model doc.

The initial doc design is for Transformers first adopters who were mainly researchers. The first two paragraphs read like they're from an arXiv paper, which makes sense, because it's something researchers are comfortable with and accustomed to.

The downside is that this type of content isn't as meaningful for developers.

• It doesn't tell you how to inference or finetune with Llama.
• It assumes users are familiar with Transformers usage patterns and APIs (initializing the pretrained model weights, preprocessing, generating, etc.).

According to an eyetracking research study by Nielsen Norman Group, users consume web content in a F-shaped pattern. The first few words on the first few lines of a page receive the most focus.

This means the model docs need to front-load the most important content in the beginning because users are eager to start using a model - whether they're familiar with Transformers or not - and experience that whoaaaaa moment of everything just working.

Some Hearthstone inspiration

While I was thinking about the next iteration of the model docs, I was inspired by Hearthstone, a deck-building strategy card game. It is easy to learn (but difficult to master) because every card tells you everything you need to know about it.

Deathwing, Dragonlord from the Whispers of the Old Gods set.

At a glance, the mana cost, attack, and health immediately stand out. Based on these values, you can intuit the games basic mechanics.

• You can only use a card if you have enough mana.
• Each card has a certain attack power and health. They dictate what happens when it interacts with an opponents card.

The text box describes a cards ability. If it is a special ability - like Deathrattle - hovering over the card triggers another text box describing its usage condition.

The card only tells you precisely what you need to know to play or use it. Nothing more, nothing less.

Every Hearthstone card follows this same design. This makes it easy to learn a new card because the design is consistent and you know what to expect. You spend less time figuring out how it works and more time on how to build a deck around it.

The second phase

The next model doc design will focus on getting a working model in the developers hands as fast as possible. Code examples will headline each model doc to deliver the most important information first.

It will also focus on bringing a consistent layout to every model doc. This allows users to easily hotswap models - if they're already familiar with an existing one - without having to be a Transformers expert.

Understanding how to generate text with Llama is applicable to generating text with Gemma and other large language models.

Spend less time reading the docs and more time coding and building.