This article is the fourth edition of the Advent of Patterns series. In this series, running from December 1st to December 24th 2024, I will document one design or programming pattern I have noticed recently. Read more about this series.
This year, I commissioned a holiday-themed mascot for my website. I wanted the holiday mascot to appear on all of my web pages: in my blog navigation, my blog favicon, my web reader, and other pages that reference the mascot. I decided to replace the existing mascot without the holiday theme, with the intent of changing the mascot back later. With one change, I could roll out a new mascot across many web pages, in many places.
This made me reflect on my experience writing documentation.
When I am writing documentation, I often link to more complete guides that explain how to perform a specific action. For example, I may say “Above, set your API key. To learn how to find your API key, refer to our API key guide.” In that text, I would link “API key guide” to the product tutorial on how to find your API key. The API key guide can go into full depth about how to find your API keys, the different types of API keys, and how to manage them.
If the instructions to find API keys change, I can always change the original source. This way, I don’t need to change every page that talks about API keys. I can change one page.
The abstract pattern is define once, reference everywhere.
In software engineering, a common phrasing of this pattern is Don’t Repeat Yourself (DRY). While there are many interpretations of the DRY theory, it is commonly used to remind engineers not to duplicate the same code in different places. If you have the same code in different places, any change to the logic of said code will need to be made in all the different places. But if you have code defined once, then referenced everywhere, you only need to change logic in one place.
I think “define once, reference everywhere” is a useful framing of DRY. Whereas DRY says what not to do, “define once, reference everywhere” says what to do: describe or define information in one place, then reference the information where it is needed.
Defining once, then referencing everywhere allows one change to propagate to all the places it needs to be made. Changing my blog mascot file let me roll out my holiday theme across multiple places. Documenting how to do something in one place, then referencing it everywhere relevant, lets me update guidance in one place rather than many. Turning code that is defined in multiple places into a function means there is one place to change – the function – when logic needs to be updated.
