Getting Started with a New Documentation Project

Overview

This guide walks you through setting up a new documentation project using the Idealogic Documentation Standards.

Before you create any modules, decide which document types your project actually needs. Read Documentation Architecture and pick a documentation profile — a shared library needs Architecture + API reference but no procedures; an operator-facing product needs the full engineering + operations set. Create a module only when you have the first real document for that type; an empty module is worse than an absent one. Each type has a per-type guide and a copy-paste page template (templates/ in doc-standard).

Prerequisites

Step 1: Get the Project Template

Clone or download the doc-standard repository:

git clone https://github.com/christhonie/doc-standard.git
cd doc-standard/project-template

The project-template/ directory contains a complete starter structure.

Step 2: Copy Template to Your Project

Create your new documentation repository:

# Create new repo
mkdir my-project-docs
cd my-project-docs
git init

# Copy template files
cp -r /path/to/doc-standard/project-template/* .
cp /path/to/doc-standard/project-template/.ai .

Step 3: Customize antora.yml

Edit antora.yml with your component details:

name: my-component-name           # Change this
title: My Component Documentation # Change this
version: '1.0'
nav:
- modules/ROOT/nav.adoc

Step 4: Update README.md

Replace the template README.md with project-specific content:

  • Project name and description

  • Links to source code repositories

  • Setup instructions

  • Team contacts

See the template README for structure guidance.

Step 5: Create Your First Module

Create a module for the first document type your profile calls for (see the IMPORTANT note in the Overview). Fetch the module-template/ from the doc-standard repository (it’s maintained centrally, not copied into each project), then follow that type’s per-type guide and page template:

# Copy the module skeleton from doc-standard (name it for the type, e.g. architecture, procedures)
cp -r /path/to/doc-standard/module-template modules/<type>

# Copy the matching page template(s) for this type
cp /path/to/doc-standard/templates/<type>-template.adoc modules/<type>/pages/<page>.adoc

# Then: fill in the page, and update nav.adoc with navigation

Each type’s structure is defined by its per-type guide: Requirements, Design, Architecture & ADRs, Operations, Runbooks, Procedures, and User Guides.

Step 6: Install Antora

Install Antora CLI globally:

npm install -g @antora/cli @antora/site-generator

Or add to your project:

npm init -y
npm install --save-dev @antora/cli @antora/site-generator

Step 7: Create antora-playbook.yml

Create a playbook to build your site:

site:
  title: My Project Documentation
  url: https://your-org.github.io/my-project-docs
  start_page: my-component::index.adoc

content:
  sources:
  - url: .
    branches: HEAD
    start_path: .

ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

Step 8: Build Your Documentation

Generate the site:

antora antora-playbook.yml

View the output in build/site/index.html.

Step 9: Set Up AI Guidance

The .ai/ directory contains templates for AI-assisted documentation.

Update .ai/DOCUMENTATION-GUIDE.adoc:

  1. Keep generic Antora structure guidelines

  2. Add project-specific context (module names, conventions)

  3. Reference the standards repo:

For comprehensive formatting standards, see:
https://github.com/christhonie/doc-standard/blob/main/docs/modules/ROOT/pages/asciidoc-style-guide.adoc

Update .ai/QUICK-START.md:

  1. Keep essential checklist

  2. Add project-specific module list

  3. Include example prompts for your project

Step 10: Commit and Push

git add .
git commit -m "Initial documentation structure"
git remote add origin https://github.com/your-org/my-project-docs.git
git push -u origin main

Next Steps

Create Content

  1. Start with index.adoc - Overview of your component

  2. Add modules - Organize by topic (architecture, api, guides)

  3. Follow the style guide - Reference AsciiDoc Style Guide for Technical Documentation

Set Up Continuous Integration

Add GitHub Actions or GitLab CI to build documentation automatically:

.github/workflows/docs.yml:

name: Build Documentation
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v2
      with:
        node-version: '16'
    - run: npm install -g @antora/cli @antora/site-generator
    - run: antora antora-playbook.yml
    - uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./build/site

Reference Standards Repository

In your AI prompts, always reference the standards:

I'm working on [project-name] documentation following Idealogic standards.

Please read:
https://raw.githubusercontent.com/christhonie/doc-standard/main/.ai/DOCUMENTATION-GUIDE.adoc

Then create [content] for the [module] module.

Common Patterns

Multi-Repository Documentation

If your project has multiple repositories (microservices):

antora-playbook.yml:

content:
  sources:
  - url: https://github.com/your-org/service-a-docs
    branches: main
  - url: https://github.com/your-org/service-b-docs
    branches: main
  - url: https://github.com/christhonie/doc-standard
    branches: main
    start_path: docs

This combines documentation from multiple repos into one site.

Versioned Documentation

Create branches for versions:

# Create v1.0 branch
git checkout -b v1.0
# Update antora.yml version to "1.0"
git commit -am "Version 1.0 documentation"
git push origin v1.0

# Continue development on main
git checkout main
# Update antora.yml version to "dev"

Update playbook to build multiple versions:

content:
  sources:
  - url: .
    branches: [main, v1.0, v2.0]

Troubleshooting

Build Errors

"Module not found":

  • Check antora.yml module names match directory structure

  • Verify nav.adoc paths are correct

"Cross-reference not found":

AI Agent Issues

AI generates wrong structure:

  • Point to .ai/DOCUMENTATION-GUIDE.adoc explicitly

  • Provide module-specific context in prompt

Content doesn’t match standards:

  • Reference the style guide URL in your prompt

  • Review and edit AI output before committing

Resources

Ready to create great documentation! Follow these standards and your documentation will be consistent, maintainable, and professional.