How to structure an engineering wiki that people actually use

An engineering wiki works when a stranger can find the right page in under a minute. That depends far more on structure and upkeep than on which tool you use.

Key takeaways

• Organise by reader intent first, then by system.
• Use predictable names so search and browsing both work.
• Give every page an owner and a last-reviewed date.
• Delete or archive what nobody uses.

Start with reader intent

People arrive at a wiki with one of a few goals. Build your top-level folders around them:

• Start here: onboarding, local setup, who to ask.
• Systems: one folder per service or product area, with an overview page.
• How-to guides: step-by-step tasks such as deploying or rotating a secret.
• Decisions: short records of why choices were made.
• Runbooks: what to do when something breaks.
• Reference: API references, data models, glossaries.

Avoid folders named after teams. Teams reorganise, and the knowledge outlives them.

Give each system an overview page

Every system folder should open with a single overview that answers: what it does, who owns it, how it connects to other systems and where the code lives. Detailed pages hang off that overview. New joiners read only the overviews first and go deeper when they need to.

Naming rules

• Use plain, searchable titles: "Deploy the API to production", not "Deployment notes v2".
• Put the system name first in reference pages so alphabetical lists group together.
• Avoid dates in titles. Use a last-reviewed field instead.

Keep it alive

1. Owner: each page names a person or team responsible.
2. Review date: stale pages should be visible as stale.
3. Link from the work: connect docs to the tasks and features they describe so changes prompt updates.
4. Prune: archive pages nobody has opened in a long while. A smaller wiki is a more trusted one.

Use structure the tool gives you

In Osco, docs live in projects with folders, and can be linked to tasks, endpoints and features. That means a service overview can point at its API reference and the open work on it, so the structure carries meaning beyond the folder tree.

Conclusion

A good wiki is a small set of well-named, owned, linked pages. Structure it around what readers need, review it on a schedule and connect it to the work, and people will keep using it.