Skip to content

AGENTS.documentation.rules.md

Latest commit

 

History

History
550 lines (389 loc) · 23.5 KB

AGENTS.documentation.rules.md

File metadata and controls

550 lines (389 loc) · 23.5 KB
Raw

Juju Documentation Rules

This file defines the core philosophy and structure for Juju documentation.

Quick Reference for AI Agents

Core principle: Follow Diataxis framework with strict modularity - content appears in ONE location only.

Documentation placement:

  • Reference = Attributes, structure, what IS (not operations)
  • How-to = Operations, lifecycle, what you DO (not attributes)
  • Explanation = Why it matters, architectural context
  • Tutorial = End-to-end learning paths

Reference docs (docs/reference/):

  • Attribute-based, never operation-based
  • Section titles keep entity/tool as subject (e.g., "Database architecture" not "How databases work")
  • Order: broad → specific (intro → architecture → implementation)
  • Link to how-to guides for operations

How-to guides (docs/howto/):

  • Title pattern: "Manage <entity>"
  • Section pattern: "To <accomplish task>, <do action>"
  • Order: lifecycle logic (create → view → inspect → modify → destroy)
  • Keep entity in section headings (e.g., "View a database's schema" not "Viewing schemas")
  • Include both manual AND automatic operations

Cross-references:

  • "See also" = lateral reference to entity/concept docs (at top of how-to)
  • "See more" = zoom-in to tool reference (after each command demonstration)
  • Place tool references AFTER output/explanation, not immediately after command
  • One reference link per new tool/command demonstrated

Visual hierarchy:

  • {warning} = Critical constraints, safety information
  • {dropdown} with :color: success = Tips, workflow advice
  • {dropdown} with :color: info = Contextual information for specific audiences
  • {dropdown} with :color: warning = About safety/write operations
  • {note} = Important practical information (always visible)
  • {ibnote} = Cross-reference links

Code blocks:

  • Use text for commands and output
  • Use sql for SQL queries and CREATE TABLE statements
  • Always include empty line before opening backticks
  • Include sample output after commands when helpful

Naming conventions:

  • "Types of <entity>" = mutually exclusive alternatives (choose one)
  • "<Entity> architecture" = coexisting parts (work together)
  • Use realistic UUIDs and model names (not "default" - use "frontend", "backend")

DO NOT:

  • Duplicate content across doc types (strict sorting: pick ONE location)
  • Put operations in reference docs (operations belong in how-to)
  • Put attributes in how-to docs (attributes belong in reference)
  • Edit autogenerated docs manually (.../list-of-juju-cli-commands/, .../list-of-hook-commands/, controller config keys)
  • Use metalanguage sections ("Prerequisites", "Tips") - integrate or use dropdowns
  • Duplicate upstream documentation (SQL, YAML, etc.) - link to it

Writing style:

  • Active voice: "To do X:" not "X can be done by:"
  • Em-dash: -- (spaces around two hyphens) in prose
  • Colon in bullet lists: **Term**: Definition.
  • Consistent entity names (controller model database, not "controller database")

Documentation Framework

The Juju documentation follows the Diataxis framework with specific implementations for each documentation type:

Reference (in docs/reference/) -- Defines what things are in Juju:

  • Concept references: High-level concepts (e.g., high-availability, scaling)
  • Entity references: Concrete entities users work with (e.g., controller, model, database, application)
  • Tool references: Commands and interfaces (e.g., juju CLI, juju_db_repl, juju-dashboard)
  • Process references: Operations and procedures (e.g., upgrading, migrating, backing up)

Juju-specific implementation for Reference:

  • Attribute-based, not operation-based: Reference docs describe what entities are (attributes, structure, characteristics), not what you do with them (operations belong in how-to guides)
  • Maintain the central subject: All section titles keep the entity or tool as the subject (e.g., "Database architecture", "Controller configuration", not "How databases work")
  • Broad to specific ordering: Progress from high-level structure to technical implementation details
  • Cross-reference to how-to: Link to operational guides for practical usage

How-to guides (in docs/howto/) -- Shows how to accomplish specific tasks:

  • Structured around entity lifecycles
  • Each section represents a moment in the lifecycle
  • Sections ordered by lifecycle logic: creation → viewing → inspection → modification → removal
  • Within lifecycle stages, order from common to specific operations

Juju-specific implementation for How-to:

  • Entity-centric titles: "Manage <entity>" (e.g., "Manage databases", "Manage controllers")
  • Task-oriented sections: Each section follows "To <accomplish task>, <do action>" pattern
  • Maintain entity focus: Section headings keep the entity as the red thread (e.g., "View a database's schema", "Query a database", not "Viewing schemas", "Querying")
  • Operations included: Document both manual and automatic operations (what happens, when it happens) -- operations belong in how-to, not reference
  • Tool references: Link to tool reference docs after demonstrating each command
  • Entity references: Link to entity reference docs at the top for context

Explanation (in docs/explanation/) -- Provides understanding and context:

  • Architectural decisions and design rationale
  • Why things work the way they do
  • Broader context for features and patterns

Tutorials (in docs/tutorial/) -- End-to-end learning paths:

  • Guide beginners through complete workflows
  • Currently minimal in Juju documentation

This framework ensures documentation serves different user needs: understanding (explanation), reference (lookup), guidance (how-to), and learning (tutorial).

Documentation Process for New Features

When documenting a new feature, follow this process:

  1. Identify the entity -- What is the new thing users will work with? (e.g., database, secret, offer)

  2. Identify the tools -- What commands or interfaces let users interact with this entity?

  3. Create entity reference (in docs/reference/) -- Define:

    • What the entity is
    • Entity attributes, structure, and characteristics
    • Entity architecture or organization (if applicable)
    • Technical implementation details

  4. Create tool reference (in docs/reference/) -- Document:

    • Complete command syntax
    • All options and flags
    • Technical details
    • Examples

  5. Create how-to guide(s) (in docs/howto/) -- Show:

    • How to work with the entity through its lifecycle
    • Use "See also" links for the entity reference (lateral reference)
    • Use "See more" links for tool references after each command demonstration (zoom-in)

This ensures users get the full picture: what it is (entity reference), how to use it (how-to), and detailed command reference (tool docs).

Autogenerated Documentation

DO NOT manually edit autogenerated reference documentation. These files are regenerated from source code during the documentation build process. Any manual changes will be overwritten.

Currently autogenerated documentation:

  • Juju CLI command reference -- All individual command pages in docs/reference/juju-cli/list-of-juju-cli-commands/
  • Hook command reference -- All individual command pages in docs/reference/hook-command/list-of-hook-commands/
  • Controller configuration keys -- docs/reference/configuration/list-of-controller-configuration-keys.md

Note: Model configuration keys (docs/reference/configuration/list-of-model-configuration-keys.md) has a generator script at scripts/md-gen/model-config/main.go but is not currently invoked by the autogeneration process. Verify the generation status before making substantial edits.

To update autogenerated documentation:

  • For CLI commands: Update command definitions in the source code and command help text
  • For hook commands: Update hook command definitions in scripts/md-gen/hook-commands/
  • For controller configs: Update controller configuration schema in source code
  • Regenerate: Run make autogenerate-docs from the docs/ directory

See: docs/scripts/autogenerate-docs.py for the complete autogeneration implementation.

How-to Guides

Entity-Centric Structure

How-to guides are organized around entities (controllers, models, databases, applications, etc.). Each guide answers: "What can I do with this entity?"

Title pattern: "Manage <entity>" (e.g., Manage controllers, Manage models, Manage databases)

Entity Lifecycle Ordering

Sections within a how-to should follow the entity's lifecycle logic:

  1. Access/Create -- How to get or create the entity
  2. List/View -- How to see what exists
  3. Inspect -- How to view details or configuration
  4. Modify -- How to change the entity
  5. Query/Use -- How to work with the entity
  6. Remove/Destroy -- How to delete the entity

Not all entities have all stages. Order sections logically based on typical workflows.

Example (Manage databases):

  • Access databases
  • View the database cluster
  • List databases
  • Switch to a database
  • View a database's schema
  • Query a database
  • Query across databases
  • Modify a database
  • View a database's change history

Section Structure

Each section should follow the pattern: "To <accomplish task>, <do action>"

Good:

  • "To switch to a model database by its name:"
  • "To see what columns and data types a table contains:"

Avoid:

  • Generic headings like "Prerequisites" or "Tips"
  • Command-centric organization ("Run .tables")

Context Establishment

Balance context establishment to support both first-time readers and returning users who jump to specific sections.

Pattern:

  • Establish once: An early section (e.g., "Access the databases") establishes the working environment
  • Self-contained sections: Each section should be understandable on its own for users who return directly to it
  • Clarify transitions: Add brief context when the interaction model changes or when a command's syntax differs significantly

Example:

  • "Access the databases" establishes you're working in the REPL
  • Sections showing dot commands (.models, .switch, .tables) are self-contained because the dot prefix signals REPL context
  • "Query a database" adds clarifying context ("type SQL statements directly at the REPL prompt") because raw SQL lacks visual cues and users may return to this section repeatedly

Rationale: Users often return to how-to guides to reference specific tasks. Sections should be independently usable without requiring full re-reading, while avoiding verbose repetition in every section.

Child Entities and Bridge Sections

Guides can include subsections for child entities when they're tightly coupled to the parent.

Example: In "Manage actions", include:

  • Manage action tasks
  • Manage action operations

Bridge sections can connect to related entities:

  • In "Manage clouds", include "Manage cloud credentials" that links to the full "Manage credentials" guide

Lateral References

Link to concept docs at the top of how-to guides using {ibnote}:

```{ibnote}
See more: {ref}`entity-concept`, [External docs](https://...)

> **Note:** Consider placing a brief intro sentence before lateral reference links for better AI processing. Starting documents with links may cause AI systems to prioritize link-following over content understanding. This pattern is under review.

Link to **tool references** at the end of relevant sections using "See more" `{ibnote}` (zoom-in principle):

```markdown
```{ibnote}
See more: {ref}`command-reference`


**When to include tool reference links:** Include a reference link after demonstrating each new tool or command. This provides readers immediate access to complete technical details.

**Placement within sections:** Tool reference links should appear after showing command output and providing explanation, not immediately after the command itself. This allows readers to see what a command does before diving into detailed reference documentation.

**Good:**
```markdown
To list all tables:

\`\`\`text
.tables
\`\`\`

Sample output:

\`\`\`text
table_name
application
unit
\`\`\`

\`\`\`{ibnote}
See more: {ref}`juju-db-repl-tables`
\`\`\`

Avoid:

To list all tables:

\`\`\`text
.tables
\`\`\`

\`\`\`{ibnote}
See more: {ref}`juju-db-repl-tables`
\`\`\`

Sample output shows...

Content Hierarchy: At-Issue vs Not-At-Issue

Use dropdowns for supplementary content readers can choose to view. Label clearly:

  • Tip: -- Workflow advice, best practices
  • Background: -- Conceptual information that provides context
  • Troubleshooting: -- Problem-solving help
  • About... with :color: warning -- Critical safety information

Naming guidance: Use "Background:" for conceptual information, not "Reminder:" (which implies the reader has seen it before).

Placement: Immediately before where most relevant (after intro paragraph, before the command).

Example:

```{dropdown} Background: What's a view?
A view is a virtual table defined by a SQL query.

## Writing Style

- Use **entity names** consistently (controller model database, not "controller database")
- Use **em-dash** as ` -- ` (two hyphens with spaces) in prose paragraphs
- Use **colon** in bullet lists where a bolded term is followed by its definition or description, and end with a period:
  - Good: `**Authentication required**: Only authenticated agents can access the database.`
  - Avoid: `**Authentication required** -- Only authenticated agents can access the database`
- Use **active voice**: "To do X:" not "X can be done by:"
- Provide **context**: "In a model database, to view applications:"
- Use `text` for code blocks (not `bash` or `sh`)
  - **Exception:** Use `sql` for SQL queries and CREATE TABLE statements to enable syntax highlighting
- Keep code blocks clean: empty line before and after triple backticks
- Include sample output after commands when helpful
- Use realistic UUIDs and names in examples

## Upstream Documentation

**Point to upstream; don't duplicate.**

When Juju documentation references technologies maintained by external projects (SQL, YAML, cloud APIs, etc.):

- **DO** link to upstream documentation as the source of truth
- **DO** provide brief guidance on how to use that technology with Juju (e.g., "To modify data, use standard SQL write operations")
- **DON'T** duplicate upstream syntax references, tutorials, or specifications

**Good:**
```markdown
To modify data, use standard SQL write operations.

```{ibnote}
See more: [SQL documentation](https://www.sqlite.org/lang.html)


**Avoid:**
```markdown
To modify data, use standard SQL write operations:

INSERT INTO table_name (column1, column2) VALUES (value1, value2);
UPDATE table_name SET column1 = value1 WHERE condition;
DELETE FROM table_name WHERE condition;

Rationale: This keeps our documentation coherent while avoiding maintenance burden and version drift. We maintain Juju-specific guidance; upstream maintains their specifications.

Version Information

Mark version-specific features immediately after the title:

```{versionadded} 4.0

## What to Avoid

- Metalanguage sections ("Prerequisites", "Tips") -- integrate or use dropdowns
- Command-first organization -- organize by entity, not command
- Generic troubleshooting sections -- place contextually as dropdowns

## Concept Documentation

Concept docs (in `docs/explanation/`) explain **what** an entity is, **why** it matters, and **how** it fits into Juju's architecture.

**Pattern:** A concept doc should link **down** to related tool references and how-to guides using lateral references at the end or in relevant sections.

**Example:** A database concept doc should link to:
- {ref}`juju_db_repl` (tool reference)
- {ref}`manage-the-databases` (how-to guide)

This provides readers with a complete path: concept → reference details → practical usage.

> **Future enhancement:** Consider using sphinx tags to enforce and validate these cross-reference patterns automatically.

## Reference Documentation

Reference docs (in `docs/reference/`) define **what things are** in Juju -- entities, tools, processes, and concepts. Think of an IKEA manual: when you open the package, you first get an inventory that defines each part. That's your reference documentation.

**What belongs in reference:**
- Entity definitions (controller, model, database, application, unit, etc.)
- Tool specifications (juju CLI, juju_db_repl, juju-dashboard, etc.)
- Process references (scaling, upgrading, removing things, etc.)
- Technical specifications and APIs

**Key principle:** If you're defining what something **is**, that's reference. If you're explaining why it **matters** or how it **fits** into architecture, that's explanation/concept.

**Example:** The database entity reference defines what a database is in Juju, its types (controller database, model databases), and technical characteristics. The explanation would cover broader architectural implications and design decisions.

### Section Ordering

Reference docs should progress from **broad to specific**:

1. Brief intro defining what the entity is
2. High-level structure or organization (e.g., database architecture)
3. Technical implementation details (e.g., what technology it uses)

This allows readers to understand the big picture before diving into specifics.

**Example (Database reference):**
1. What the database is (intro)
2. Database architecture (controller database, model databases)
3. Database implementation (Dqlite technical details)

**Cross-references:** Place "See also" links to related how-to guides upfront, before or immediately after the intro, so readers can quickly navigate to operational docs if needed.

## Tool Reference Documentation

Tool reference docs (in `docs/reference/`) provide complete technical details about commands, options, and usage.

### File Naming

Name reference files after the **tool name users invoke**, not the underlying technology:

- **Good:** `juju-cli.md`, `juju-dashboard.md`, `juju-db-repl.md`
- **Avoid:** `client.md`, `dqlite-repl.md`

Exception: Entity references use the entity name directly (e.g., `model.md`, `controller.md`).

### Anchor Naming

**General rule:** All anchors use lowercase with dashes as separators (no underscores).

**For document and entity references:**

```markdown
(database)=
# Database

(juju-cli)=
# Juju CLI

For section anchors within documents:

Use the full section title in lowercase with dashes replacing spaces:

(database-access-and-security)=
## Database access and security

For command references:

Commands use dashes, even if the actual command name contains other characters:

(juju_db_repl)=
# `juju_db_repl`

Command-specific anchors should follow the pattern <tool>-<command>:

(juju_db_repl-models)=
### `.models`

Section Organization

Organize tool references by tool capabilities or attributes, not by metalanguage categories:

Good (by capability):

  • Overview
  • Database architecture
  • Basic commands
  • Navigation
  • Schema introspection
  • Query execution
  • Cluster management

Avoid (metalanguage):

  • Commands
  • General commands
  • Database navigation commands

This pattern applies to CLI tools, REPLs, and other interactive tools.

Entity Reference Section Naming

Choose section titles that reflect whether you're describing mutually exclusive alternatives or coexisting parts:

Use "Types of <entity>" or "<Entity> taxonomy" when classifying alternatives:

  • Types of relations: A relation is EITHER peer OR non-peer (mutually exclusive)
  • Types of charms: A charm is EITHER subordinate OR principal (mutually exclusive)
  • Types of secrets: A secret is EITHER a charm secret OR a user secret (mutually exclusive)

Use "<Entity> architecture" or "<Entity> organization" when describing parts that coexist:

  • Database architecture: Every deployment has BOTH a controller database AND model databases (coexisting parts)
  • Controller architecture: A controller has components that work together (parts of a whole)

Rationale: "Types" implies choosing between alternatives; "architecture" implies understanding how parts fit together. This distinction helps readers understand whether they're selecting from options or learning about a system's structure.

Command Documentation

For commands that are alternatives (not aliases), list them together in the heading:

### `.exit`, `.quit`

Use Usage: for syntax specifications, not Aliases: unless one is truly an alias of another.

Cross-Documentation Patterns

When documenting a feature that spans multiple documentation types (concept, reference, how-to):

  1. Concept doc links down to tool reference and how-to guide
  2. How-to guide links up to concept doc (top) and over to tool reference (per section)
  3. Tool reference links to how-to guide for practical usage

This creates a documentation triangle where users can move between understanding (concept), reference (details), and practice (how-to).

Future enhancement: Consider sphinx tags or other tooling to validate these cross-reference patterns and ensure documentation completeness.

Avoid Duplication Across Documentation Types

Principle: Content should appear in one primary location based on Diataxis type. Use cross-references rather than duplicating content.

Strict sorting rule: Even when content could reasonably fit multiple documentation styles (e.g., a concept could be explained in reference or how-to), choose the single most useful location and use cross-references ("See also", "See more") to connect related content. Don't hedge by putting variants in multiple places.

Why this matters:

  • Reduces maintenance burden (update once vs. updating multiple locations)
  • Prevents inconsistencies and version drift
  • Forces clearer thinking about what content belongs where
  • Makes documentation easier to navigate
  • Eliminates user confusion about which version is authoritative

How to choose where content belongs:

  • Explanation/Concept: What something is, why it matters, architectural context
  • Reference: Complete technical definitions, specifications, entity characteristics (attributes, properties, structure)
  • How-to: Practical step-by-step workflows, entity lifecycle operations, operational procedures (including automatic operations)
  • Tutorial: End-to-end learning paths for beginners (we have few of these)

Key distinction for operations: If content describes when things happen or what operations occur (even if automatic), it belongs in how-to guides, not reference docs. Reference docs describe entity attributes; how-to docs describe entity operations.

When in doubt: If content serves multiple purposes, choose the most specific location and link to it from other docs. Prioritize the style that serves the most common use case.

Examples:

  • Database security measures belong in the security explanation doc, not duplicated in the database reference
  • Tool command details belong in tool reference, not duplicated in concept docs (concept docs can mention tools exist and link to them)
  • When-to-use guidance can appear in concept docs with link to how-to; brief version can appear in how-to intro
  • Emergency recovery procedures belong in operational how-to guides, not scattered across multiple reference docs

Trade-off: Occasionally, this means some content appears in only one Diataxis type even though it might seem relevant to multiple. That's acceptable -- use cross-references to guide readers where they need to go.