Antora

Documentation Sites for Software Teams

Why docs?

Documentation is the “curb appeal” of software

When deciding what projects to use, companies place a premium on good docs 48% of the time.

Steven O’Grady, RedMonk

Docs are Integral

🤔

Antora

Multi-repo static site generator

Authoring: AsciiDoc

Publishing: Antora

Multi-repo static site generator for docs

Goal

docs as code

To produce documentation sites from distributed content by reusing conventions, processes, and tools from software development.

Features

Distributed
content

Standard
structure

Standard Docs Project Structure

antora-playbook.yml

site:
  title: Couchbase Docs
  url: https://docs.couchbase.com
  start_page: home::index.adoc
content:
  branches: release/*
  sources:
  - url: .
    branches: HEAD
    start_path: home
  - url: git@github.com:couchbase/couchbase-operator.git
    start_path: docs/user
  - url: https://github.com/couchbase/docs-server.git
...

Components
repositories

Versions
branches

antora.yml

name: server
version: '6.0'
title: Couchbase Server
start_page: introduction:intro.adoc
nav:
- modules/ROOT/nav.adoc

Versions tracked in branches

Dedicated
UI project

Exports
UI bundle

Content
UI

antora-playbook.yml

...
ui:
  bundle:
    url: https://github.com/couchbase/docs-ui/releases/.../ui-bundle.zip

Plain text
docs format

CI/CD
pipeline

Demo

couchbase docs screenshot — https://docs.couchbase.com

Thank You!

antora.org

Slides & Transcript: gitlab.com/opendevise/talks/docs-sites-for-software-teams