Using components to avoid repetition in technical writing

Recently, there was a discussion about whether some quickstart guides in the Inference Python package should contain installation information. The alternative was to defer users, with a callout box, to our package installation page to learn more, which was the setup we had at the time. Having installation information on several quickstart guides is useful because we know that the audience for those guides are people who may not have used our product before. With that said, there were concerns.

My primary concern was that repeating installation information, or anything other information that would appear in several places, would increase the maintenance burden. When a fundamental primitive changed that we have mentioned in several places, we would have to make updates in every place. In theory, this sounds like a small price to pay. In practice, having the same information in multiple places increases one’s exposure to inconsistency between documentation pages.

But, there is a happy path that lets you reference information in multiple places while only requiring you edit once when required: use components to embed content in a document.

Using components

When there is information that you need to reference in several places across a documentation project, consider using components. Components are embeddable pieces of material that you can add into different pages. A component should have a single source. Thus, you only need to update content once for it to show up in all places where the content is referenced.

Here is an example of a component in the Roboflow Inference documentation:

When the component source changes, all instances where the component is referenced change. For us, having the installation process as a component is useful because we may want to make changes to cater to the needs of more users (i.e. add Docker instructions in a hidden tab, create an interactive widget to choose how to install the package in different environments, etc.).

Roboflow Inference now has a similar setup for our installation and model ID instructions. We use mkdocs for our documentation, for which there is an extension to support embedding content called mkdocs-macros-plugin. This component allows us to create an includes folder in our directory where standard components are referenced. We can reference them in our docs like this:

% include 'install.md' %

When our docs are rendered to the end user, this block is replaced with the contents of he includes/install.md file.

I have seen several documentation sites use components behind the scenes. Earlier this year I contributed to the Supabase documentation. Their documentation had components for creating projects, a common task relevant to many guides. Creating a project was a prerequisite for following many tutorials. Rather than refer the user to another page, the guide included exactly the project text the reader needed to ensure the guide was an end-to-end tutorial. For a documentation author, one needs to embed the component in a similar manner to the example described above to use the component in a guide.

When you should use components

Components are useful when you have a standard procedure or prose that you want to include across multiple pages. Ideally, a component should include too many instructions. Showing an installation process or how to set up a primitive that is not too complex are effective uses of components, as long as that information is something relevant to many pages. For long tasks, or tasks that are secondary to guides, consider having a separate page in your documentation and linking to it instead of embedding a component.