Good documentation isn't about explaining your tool. It's about making sure someone else can own it.
Imagine this: someone set up a tool before you arrived. No README, no comments, no context. It works, until it doesn't. And when it breaks, you're reverse-engineering someone else's decisions without knowing what constraints they were working under, what they tried first, or what the tool was never meant to do.
That's the cost of skipping documentation. Not a missed readme. Actual time and money, compounded every time someone new touches an existing system.
I wrote about this briefly on ArtStation a while back - going more into the practicalities and implications of doing documentation for others. This is the expanded version, with more practical detail on what I've actually seen go wrong and how I approach it now.
What Documentation Is Actually For
The default instinct is to write documentation for the tool. That's the wrong approach.
Documentation is for the person who comes after you or the one that has to use it daily. Whether that's a vendor picking up your texturing pipeline, a developer joining mid-project, or you eight months from now when you've forgotten how something works.
That means three things have to be true:
It has to be easily accessible. Information scattered across Confluence pages, Slack threads, and a half-cooked wiki is effectively lost. If someone has to ask where the docs are, they're not going to use them.
Who is your target audience. A developer picking up a tool for the first time needs different depth than someone who worked on the same engine for three years. Writing one document for both audiences means it's useful to neither.
It has to be maintained. Documentation that was accurate six months ago and hasn't been touched since is worse than no documentation. If a workflow changes and the docs don't, you're actively misleading the next person.
None of this is complicated in principle. The failure is usually in assuming that the document you wrote at launch is done.
What Goes Wrong
Most documentation failures fall into a small number of patterns, and they compound.
Ambiguous scope. The document doesn't say what it covers or who it's for. Is this the full material pipeline or just the blend workflow? Is it targeting artists or TAs? Readers spend time in the wrong section or miss the section they needed.
Inconsistent terminology. If the document says "master material" in one place and "base material" in another, and those mean the same thing, readers slow down to verify. If they mean different things and it's not explained, readers make assumptions, and those assumptions produce errors downstream.
Redundancy that creates skimming. When the same information appears in multiple places, readers learn to skim. Once skimming is the default reading mode, they start missing things that only appear once.
Complexity without hierarchy. Dumping advanced workflow steps alongside basic setup instructions treats all information as equally important. It isn't. A new team member trying to set up a material needs to get through basic setup before they can use height blending. Structure the content in the order someone would actually encounter it.
Not accounting for language. Depending on your vendor relationships, the people reading your documentation may not be native English speakers. Passive voice, idiom-heavy writing, and long compound sentences create unnecessary friction. This is easy to fix and almost always overlooked.
How I Structure It
The structure that's worked best for me is a two-axis hierarchy: topic and complexity.
Texturing & Materials/
├── Overview ← what this section covers, who it's for
├── Basic Workflow/
│ ├── Simple Material Blend
│ └── Bespoke Texturing
└── Advanced Workflow/
└── Height Blend
Each section starts with a one-paragraph summary: what this covers, what you need to know first, and who it's relevant to. That alone eliminates most of the "I read the wrong section for 20 minutes" problem.
The complexity split is deliberate. Not every artist needs the advanced workflow. Separating them means the basic workflow stays clean, and the advanced section can go deeper without worrying about overwhelming someone who's just getting started.
For tooling documentation specifically, I add a fourth section: known limitations and open questions. If a tool has edge cases that produce bad output, or if there's a workflow that's undocumented because it wasn't finished, that belongs in the docs. The next person is going to hit those limits. Better they know upfront.
The Iteration Loop
Writing documentation once isn't enough. The loop that actually works:
1. Walk through it yourself, step by step. Follow every documented instruction exactly as written, as if you'd never used the tool. This catches gaps immediately: steps that seem obvious in your head but aren't on the page, missing prerequisites, wrong button labels.
2. Buddy check. Have someone else follow the same steps independently. Not someone who already knows the tool; someone who has the target knowledge level but not the tool-specific knowledge. Watch where they hesitate or ask questions. Those are the gaps.
3. Update when workflows change. Tie documentation updates to tool or pipeline changes, not to a separate review cycle. If a change ships without updated docs, the docs are already wrong.
4. Evaluate blockers in shared assets. If artists are running into issues with shared shaders or the material library, that's documentation signal as much as it's a tooling issue. Recurring questions usually mean the answer isn't where it needs to be.
The goal isn't a perfect document; it's a document that reduces confusion faster than confusion accumulates.
What I'd Do Differently
A few things I'd change if starting from scratch on a documentation project:
Proof of concept before writing. Before writing full documentation, show a one-page layout of the proposed structure and get sign-off. It's much faster to argue about organization at that stage than after ten pages are written.
Visuals from the start, not as an afterthought. Screenshots, annotated diagrams, short video walkthroughs: these reduce confusion significantly, especially for visual learners and non-native readers. Adding them retroactively is tedious. Building them in from the beginning is a better habit.
Delegate by department early. TAs shouldn't be writing the artist-facing workflow documentation and the developer-facing API documentation. Get the right people owning the right sections from the start. Coordination takes effort, but the output is documentation that actually reflects how each team uses the tool.
Don't get attached to what you wrote. Good documentation requires being willing to cut sections, restructure, and rewrite. If a section isn't working, the answer isn't to add more explanation; it's to reconsider the structure. Version control makes this low-risk.
The Real Cost of Getting It Right
Documentation feels like overhead until you're the one debugging a tool someone else built without any. Then it feels like the most valuable thing that could have existed.
The industry is built on handoffs: between teams, between studios, between projects, across years. Documentation is what makes those handoffs work. It's not a nice-to-have for polished pipelines. It's how you prevent the next person from starting from zero.
Build the habit early. Revisit it consistently. And write it for the person who wasn't in the room when the decisions were made.
© 2026 Stefan Groenewoud - All views are my own, not those of my employer.