Skip to content
All articles

What we borrowed from five documentation systems

Borrow task flow, focused page types and clean exports without copying another documentation system.

Ouros editorial team

The most useful thing to borrow from a mature documentation system is its way of helping a reader finish a task. Copying its sidebar or component tags is less valuable than understanding why it puts requirements, actions and checks in a particular order.

Five sources, different strengths

GitHub's article model makes the parts of an article explicit. It helps a writer ask whether the introduction promises a clear outcome and whether prerequisites appear before the action that needs them. Borrow that discipline without importing a different product's terminology or every historical exception in its corpus.

Cloudflare's Workers quickstart shows how a command-line task can be divided into named phases. A reader can complete the main path without absorbing every optional explanation first. The useful pattern is the separation of required actions from background, not the exact component syntax used to render it.

Supabase's page-structure guide distinguishes task instructions, explanations and reference. A page that tries to teach the entire system while also serving as a precise field lookup usually does both badly. Keep one reader question in charge and link to the deeper explanation when needed.

Stripe's Markdoc article explains the value of declarative content and controlled interactive components. That does not mean every team should migrate frameworks. Keep ordinary content readable as text, and give richer components a small, reviewed interface rather than allowing arbitrary application code in every article.

Vercel's Markdown access guidance shows why an alternate text representation can be useful to tools and readers. The alternate should contain the same selected article, not an outdated summary or a second independently maintained version.

Try the pattern on one article

Write a guide with an outcome, requirements, a short action path and an observable check. Then read it without the surrounding site. Can you tell what you need, what to do and how to know it worked? Add only the context that repairs a real gap.

If you offer both HTML and Markdown, compare headings, code, warnings and links. Here is an example of metadata that relates those representations; it is not a claim about the headers currently returned by a site:

<link rel="canonical" href="https://docs.ouros.md/docs/getting-started/fast-notes">
<link rel="alternate" type="text/markdown" href="https://docs.ouros.md/docs/getting-started/fast-notes.md">

Structured article data should also describe the visible article truthfully. This example names the article, product and publisher. It does not create a special search ranking or supply an invented author:

{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Save your first note",
  "url": "https://docs.ouros.md/docs/getting-started/fast-notes",
  "about": {
    "@type": "SoftwareApplication",
    "name": "Ouros X"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Ouros",
    "url": "https://ouros.md/"
  }
}

Keep the synthesis yours

Use the primary sources to explain a decision, not to repackage their full documentation. Different teams make different tradeoffs. A table can clarify comparable fields, but it is a poor home for a long procedure. Tabs can separate genuine platform alternatives, but should not hide sequential steps.

This reusable source block is a writing template. Replace its prompts with your actual sources and method before publishing a finished article:

## Sources and method

- Primary source: [CommonMark reference](https://commonmark.org/help/).
- Method: source-based synthesis with an original worked example.
- What we checked: list the source passages and any executed example.
- Limits: identify what was not tested.

This article shares what we learned; it is not the source publisher’s official documentation.

Start with the blueprint's page templates and parity card, then use the reading paths for a deeper comparison. The aim is a reader who can do something useful, with an explanation that remains accurate in every published representation.

Sources

Put it to use