Idealogic Documentation Standards

Overview

This repository provides standardized guidelines, templates, and tools for creating professional technical documentation across Idealogic projects. The standards support both human contributors and AI-assisted documentation generation.

Why These Standards?

Antora + AsciiDoc provides a powerful combination for technical documentation:

  • Modular Structure - Organize documentation into logical modules

  • Version Control - Documentation lives with code in Git

  • Multi-Site Generation - Combine multiple documentation components

  • Semantic Markup - AsciiDoc offers rich formatting without HTML

  • Consistency - Standardized structure across all projects

What’s Included

This standards repository contains:

Documentation Architecture

What document types exist, how they fit together, and how to choose the ones your project needs
Document-Type Guides

How to build each type — Requirements, Design, Architecture & ADRs, Operations, Runbooks, Procedures, User Guides
AsciiDoc Style Guide

Content formatting and writing standards
Antora Configuration Guide

Module management and project structure
AI Guides

Templates and instructions for AI-assisted documentation
Project Template

Complete starter structure for new documentation projects
Rationale

Why we chose Antora and AsciiDoc
Getting Started

How to set up a new documentation project

Quick Start

For New Documentation Projects

  1. Clone or download the project-template/ directory from this repository

  2. Customize antora.yml with your component name

  3. Update the template README.md with project-specific information

  4. Start creating documentation modules

For AI-Assisted Documentation

Point AI agents to the standards in this repository:

Please read the documentation standards from
https://github.com/christhonie/doc-standard

Specifically:
- .ai/DOCUMENTATION-GUIDE.adoc for comprehensive guidelines
- .ai/QUICK-START.md for quick reference

Standards vs. Project-Specific Content

Content Type Location Purpose

Generic Standards

This repository (doc-standard)

Reusable across all projects

Project-Specific

Individual project repos

Custom content, examples, context

Style Guide

This repository

Universal formatting rules

Project README

Individual project repos

Project-specific setup and context

Repository Structure

doc-standard/
├── .ai/                         # AI guidance files
│   ├── DOCUMENTATION-GUIDE.adoc # Comprehensive AI guide
│   ├── QUICK-START.md           # Quick reference
│   ├── MODULE-README-TEMPLATE.md
│   └── PROJECT-STRUCTURE.md
├── module-template/             # Template for new modules (centralized)
│   ├── nav.adoc
│   ├── DEPENDENCIES.txt
│   ├── pages/
│   ├── images/
│   ├── examples/
│   └── partials/
├── docs/                        # Antora documentation component
│   ├── antora.yml
│   └── modules/ROOT/
│       └── pages/
│           ├── index.adoc                  # This file
│           ├── asciidoc-style-guide.adoc   # Content formatting
│           ├── antora-configuration-guide.adoc  # Module management
│           ├── rationale.adoc
│           └── getting-started.adoc
└── project-template/            # Template for new projects
    ├── README.md
    ├── antora.yml
    ├── .ai/
    └── modules/

Note: The module-template/ is maintained centrally in doc-standard (not in project-template). Derived projects fetch it from here when creating new modules.

Using These Standards

In Your Documentation Project

Reference the standards in your project’s .ai/DOCUMENTATION-GUIDE.adoc:

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

With AI Agents

When working with AI assistants:

I'm creating documentation following the Idealogic Documentation Standards.
Please read:

https://raw.githubusercontent.com/christhonie/doc-standard/main/.ai/DOCUMENTATION-GUIDE.adoc
https://raw.githubusercontent.com/christhonie/doc-standard/main/.ai/QUICK-START.md

Then help me create [specific content] for the [module-name] module.

Contributing to Standards

To propose changes to these standards:

  1. Fork this repository

  2. Create a feature branch

  3. Make your changes

  4. Submit a pull request with rationale

Changes should be generic and applicable across multiple projects.

Support

For questions about these standards:

Additional Resources

These standards enable consistent, high-quality documentation across all Idealogic projects.