✶Write some Docs

Adding some creativity into your docs

In my first post, I gave a brief overview of how I've come to prefer architecting my docs in such a way that they are independent from the frontend. This comes with a few benefits such as:

  1. Decoupling your docs from systems, making them plug and play
  2. Building automated backups with redundancy by design
  3. Indexed manifests to allow other features
  4. Serving the same docs from a single golden source
  5. Repos can be purely content using CI/CD publish pipelines

It's specifically points 3 and 4 I want to home in on in this post.

What do you mean by other features?

Addressing the question head on, what do I mean? When looking at an option for your docs site, you might consider one of the static site generators, Confluence or some other product. I tend to see these options and think that documentation gets left behind in terms of pushing boundaries of new features. I think part of that is due to how content is coupled to the system it is hosted on.

For example, when looking at a potential offering we tend to have a checklist in our heads of what we need:

  • Search
  • Navigation
  • Media compatibility (images, video, maybe interactive code)
  • Some text

I'll not pretend to have unlocked a whole new set of features but I think there's a level of creativity not being tapped into.

Looking for inspiration for this untapped creativity

Some of my hobbies include boardgames, tabletop role-playing games (TTRPGs) and video games. While at first pass this might seem irrelevant, you might be surprised at what you can find. One such example I came across was from the video game (based on the TTRPG of the same name) Rogue Trader.

Rogue Trader is based on the Warhammer 40k franchise, and for those who don't know, it's a very dense universe with 100s of books, many video games, and of course the tabletop game itself. So creating a game based on this is quite a challenge, as you don't want the players to feel left out or to miss context. But how do you drip feed this into a video game?

The answer is tooltips throughout the dialogue.

Rogue Trader dialogue with pop-up excerpt of a potentially unfamiliar term

Diving into this a bit more:

  • Players can see when more context is available and get it when they want
  • Information can be drip-fed to players instead of handing large bodies of text

The issue here in a video game is that it'll disappear, potentially never to be seen again. But this isn't a problem with docs since users can stay on a page or bookmark and come back.

Taking docs lessons from Rogue Trader

As mentioned, one of my hobbies is TTRPGs, another one of them is building web apps. This pairs nicely for someone that has ideas of creating a TTRPG system. It is here that I wanted to test out this Rogue Trader idea by pairing it with the dynamic docs one.

As part of the dynamic docsAn intro to dynamic docsArchitecting docs as separate layers: a frontend, content with a build step, and isolated storage such as S3.Read more approach, creating a manifest is necessary to render a navigation, easily load docs via filepath using minimal API calls, and essentially insert the docs into the docs site. With this manifest comes a nice side-effect. We can include things such as the page metadata.

By metadata, I mean the frontmatter that is typical to see in a docs-as-code approach, it typically looks like this and is placed at the start of a markdown file:

---
title: Adding some creativity into your docs
date: 2026-07-13
excerpt: When your docs are stored independently, you gain a lot of freedom in delivery.
---

In this case, we're interested in the excerpt field. The excerpt is usually a one-liner, in docs, it might just give a high-level summary of what the page is about. What the manifest lets us do in this case is retrieve excerpts whilst we're already loading the page from the manifest, giving us the opportunity to do the below:

Tooltip idea showing high-level info for term inside a docs site

In this site, we're building on the idea of skill checks. I'll not explain the term here but needless to say it's a fundamental concept for a player to understand. In this context, I want to make sure the player understands exactly what term I mean when I reference it, and can quickly check it without leaving the page they are currently reading.

The below shows the flow of this display method:

That being said, it does have weaknesses to be aware of:

  • Dead links become more obvious: You need to be sure when you move a file that it isn't referenced anywhere else, and update references when it is.
  • Style guide is king: You need to consistently apply the same approach to the excerpts or their equivalent, short, to the point, and not jargon heavy.

Golden source

What this feature also solves is embedding multiple definition sources into docs. Dynamic docs means we could in theory roll this feature out to a product UI too, the UI would simply ingest the docs manifest file and parse the filepath/doc name and extract the excerpt. The beauty here is that we only have to maintain the docs golden source, the UI will fetch the manifest and is ignorant as to what it contains or when it is updated, only that it's there.

When tech writers are updating a document, they can also update the excerpt in the same pass and file, which then propagates to the product UI itself with zero extra effort.

Rounding off

This is just one example I'm starting to implement, but it's one that reminds me to look for inspiration from places other than docs sites. It's also one that was easily implemented due to the dynamic docs approach.