In a design system, why keep component documentation as code beside the component rather than in a separate wiki?
answer
- two sources drift apart
- same change, same review
- versioned with the release
- the build can check it
- docs in the definition of done
basics
~20 sDocs kept beside the component change in the same review as its code, are versioned and released with it, and can be checked by the build, so an API change without a docs update is caught instead of drifting silently.
solid answer
~50 sDocumentation drifts whenever what it describes changes somewhere else. **Docs as code** puts each component's page in the same repository and folder as the component, as plain-text source built into the site, so a change to the component and a change to its page travel in **the same change request and review**. That coupling in time is the mechanism: the reviewer can ask 'where is the docs update?' at the moment it is cheapest, and many teams make it part of the **definition of done**. The docs are also **versioned with the release**, and the build can check links and render examples. It is not a guarantee — it keeps docs near the code, not well written, and it needs a path for designers to edit — but it turns drift from a reader's discovery into a review finding.
go deeper
Recall that docs as code keeps each page beside its component, reviewed in the same change and released with the same version.
Explain coupling in time — docs reviewed with the code change — and what it cannot fix: poor prose, pages with no component, reviewers who skip the docs.
Show how you would make docs part of the definition of done, add a build check for unchanged pages, and keep a review-backed editing path open for designers.
Weigh the engineering-centred workflow against designer participation, and decide which content lives beside code and which needs a separately owned home.
## The drift problem A **design system** — shared tokens, components, patterns and documentation used by many product teams — depends on documentation that tells the truth. Documentation **drifts** whenever the thing it describes changes somewhere else: a component gains a property, a default changes, a variant is removed, and the page in a separate wiki still describes last quarter's component. Teams build to the page, hit the difference in review or in production, and learn to distrust the docs. Once teams distrust the docs, they ask the system team directly or copy each other's screens, and the docs stop doing their job even where they are correct. ## What docs as code means **Docs as code** treats documentation the way source code is treated: - **Location**: the page lives in the same repository, usually the same folder, as the component it describes. - **Format**: plain-text source files that a docs build turns into the site, rather than content stored in a hosted editor. - **Review**: a change to the component and a change to its page travel in the same change request and are reviewed together. - **Versioning**: the docs are tagged and released with the code, so the docs for 3.2 are the docs that shipped with 3.2. - **Checks**: the build can verify links, render examples and flag a component whose public surface changed with no docs edit. ## Why it keeps docs current | Question | Separate wiki | Docs as code | |---|---|---| | When is the page updated? | Whenever someone remembers | In the same change as the code | | Who reviews it? | Often nobody | The component's reviewers | | Which version does it describe? | Whatever the latest edit matches | The version it was released with | | How is drift noticed? | A reader hits it | Review or a build check catches it | | Who can edit? | Anyone, untracked | Anyone, through review | The key mechanism is **coupling in time**. When the docs change in the same review as the code, the reviewer asks for the update at the one moment it costs least — the author still has the change in their head. Many teams write this into their **definition of done**: a component change is not finished until its page reflects it. Because the docs are released with the code, a team can also read the page exactly as it stood at the version they installed, rather than a page that has moved on without them. ## A worked example On a music-streaming app, the design system's **track row** — the list item showing a song title, artist, duration and actions — gains an 'explicit content' marker. In a docs-as-code setup, the change request contains the new property, the updated page explaining when the marker appears, and a new example the docs build renders. The reviewer sees all three together and can reject a change that adds the property without explaining it. In a wiki setup the code merges, the wiki is updated three weeks later or never, and a team building a new playlist screen learns about the marker from a bug report. ## What it does not solve Docs as code is a mechanism, not a guarantee: 1. **It keeps docs near the code, not good.** Unclear guidance or missing reasons stay unclear until someone writes better prose. 2. **It can shut designers out** if editing needs tools they do not use. Provide a browser-based editing path that still goes through review, or pair designers with engineers on doc changes. 3. **Not everything has a component to sit beside.** Principles, foundations and cross-component patterns still need a home and a named owner. 4. **Review discipline still matters.** If reviewers approve component changes without looking for the docs edit, co-location alone changes little; a build check that flags an unchanged page is a useful backstop. ## Across platforms A system that ships to the web and to native mobile keeps each platform's implementation notes beside that platform's component, while shared guidance — when to use, anatomy, accessibility intent — lives once and is referenced by both. A native mobile team changing its track row updates its own notes in the same review, and the shared guidance is not forked into per-platform copies that drift from each other.
- How do you keep designers able to contribute when docs live in the code repository?Give them an editing path that does not require local development tools — a browser-based editor that opens a change request, or a preview build for every change — and keep the source format simple plain text. Review still applies, so quality holds. Pairing a designer and an engineer on doc changes for new components also spreads the habit.
- What build check best backs up review for docs as code?A check that compares a component's public surface with its documentation: if a property is added, renamed or removed and neither the page nor the generated reference changed, the build warns or fails. Adding link checking and rendering every example in the build catches the other common kinds of drift without depending on a reviewer's memory.
saying these in an interview costs you the question
- Docs in the code repository keep themselves current automatically.
- Docs as code means designers can no longer contribute to documentation.
- A wiki stays just as current if people are reminded to update it.
- Docs only need updating at the end of a release, not with each change.
- Docs as code means every word of the documentation is generated.