Skip to content

New: AI StudioSee AI Studio

Loading

    All use cases

    Updated

    Use case · Websites & Marketing Sites

    Documentation site

    Product documentation that is easy to search, easy to keep current and readable by AI assistants as well as people.

    An illustration of the kind of software we can build, not client work.

    What is a documentation site?

    A documentation site is the public home of a product's guides and reference material. Content is typically written in Markdown and stored with the code, so it is reviewed and versioned like software, and the site adds search, navigation and an API reference generated from the specification. Increasingly it is also written to be read by AI assistants.

    When it is needed

    A product needs a proper one when support answers questions the documentation should have covered, when developers evaluating an API cannot find what they need, or when the existing documentation lives in a help-desk tool that cannot version it alongside the product.

    What it includes

    1. Content written in Markdown and versioned with the code
    2. Search across guides and API reference
    3. API reference generated from the specification
    4. Structured data and an llms.txt file for AI search

    Before the build

    Decisions to make early

    1. Docs as code or a hosted tool

      Keeping documentation in the repository suits developer products and engineering-led teams. A hosted editor suits teams where non-developers write most of the content.

    2. How the content is organised

      Tutorials, how-to guides, reference and explanation serve different needs. Mixing them on one page serves none of them well.

    3. How it stays current

      Tie documentation changes to product releases, and generate the API reference from the specification so that it cannot fall behind.

    What tends to go wrong

    • Reference pages written by hand that no longer match the API.
    • Search that cannot find a page by the word users actually type.
    • Code samples that were never run.

    Where it fits

    Typically connects to

    • GitHub
    • OpenAPI specification
    • Vercel

    Teams that use it

    Industries

    Services involved

    FAQ

    Documentation site: questions and answers

    What is docs as code?

    Docs as code is the practice of writing documentation in plain text files, usually Markdown, stored in the same version control system as the software. Changes go through the same review and release process as code. For a documentation site it means the content is versioned with the product and can be checked automatically.

    How do you make documentation readable by AI assistants?

    Documentation is readable by AI assistants when pages are served as plain HTML without requiring scripts, each page covers one topic under descriptive headings, and code samples are complete. Many documentation sites also publish an llms.txt file listing their key pages, and offer a Markdown version of each page.

    Build it. Ship it. Grow it.

    Book a free 15-minute call. No sales pitch, just an honest conversation about where you are and what it would take to get where you want to be.

    Book a call. It's free

    15-minute call. No commitment.