Publishing Tools — Choosing Where Content Lives
Nightjar now has four kinds of content: API docs, help articles for customers, launch posts, and runbooks for the on-call team. Someone suggests putting all of it in one tool. It would not work. Support agents cannot fix a help article if every edit needs a Git pull request, and marketing will not open a pull request to schedule a blog post.
The rule
Publish content where the people who maintain it can keep it true.
Content goes stale the moment the people responsible for it find it hard to edit. So the right home depends less on features and more on who maintains the content, and what makes it change. The main families:
| Home | Best for | Who usually edits | Watch out for |
|---|---|---|---|
| Static site generator (docs as code) | Developer docs, API reference | Writers and engineers, through Git | Contributors need Git |
| Help centre or knowledge base | Customer help articles | Support and writers, in a web editor | Weaker review and versioning |
| Blogging platform or CMS | Tutorials, announcements | Marketing and writers | Not built to track product releases |
| Internal wiki | Team notes, runbooks | Anyone on the team | Pages go stale without owners |
A static site generator turns a folder of Markdown files into a website; Docusaurus, MkDocs, Hugo and Sphinx are well-known examples. Because the source sits in Git, docs are reviewed like code and can keep a separate version for each product release. Blogging platforms add what a blog needs, such as scheduled publishing, author pages, categories and fields for search-engine titles and descriptions.
The shortcut
Ask three questions: who edits it, what makes it change, and who reads it? The answers point to the home.
API reference
Engineers and the writer edit it; it changes with each code release; developers read it publicly. Home: the docs-as-code site in the repository.
The trap is copying the same facts into several homes. The setup steps in the blog, the help centre and the docs site will drift apart until they contradict each other. Keep each fact in one place and link to it from the others.
Drills
Answer fast — trust the rule.
Which content fits a docs-as-code site best?
Support agents must update help articles the same day they spot a problem, and none of them use Git. Which home fits?
What is the risk of copying the same setup steps into the blog, the help centre and the docs site?
Nightjar supports two versions of its API at the same time. Which publishing feature matters most for its reference docs?
Remember
- Publish content where the people who maintain it can keep it true.
- Shortcut: ask who edits it, what makes it change and who reads it.
- Trap: copying the same facts into several homes instead of linking to one source.