Documentation Guide

In Plumego, documentation is not secondary to code.

Documentation defines intent,
while code implements that intent.

If code and documentation ever diverge,
documentation wins — and the code is considered wrong.

This page explains how documentation is written,
reviewed, and maintained in Plumego.

Documentation Is a Contract

Plumego treats documentation as:

• A behavioral contract
• A design boundary
• A long-term memory of intent

Documentation is not:

• Marketing copy
• A tutorial-only resource
• Optional explanation
• “Nice to have” commentary

Every documented behavior is a promise.

Who Should Write Documentation

If you:

• Change behavior
• Introduce a concept
• Add or remove guarantees
• Modify semantics
• Affect user mental models

You are responsible for updating documentation.

“No documentation change needed” is rarely true.

Documentation Hierarchy

Plumego documentation is intentionally layered.

Understanding where to write matters as much as what to write.

1. Concepts

Purpose:

• Explain what something is
• Define mental models
• Describe invariants

Rules:

• No how-to steps
• No API details
• No implementation discussion

Concepts explain why and what, not how.

2. Architecture

Purpose:

• Explain structural decisions
• Define boundaries and dependency directions
• Clarify responsibilities

Rules:

• No code-level walkthroughs
• No feature promotion
• No shortcuts

Architecture documents constraints.

3. Guides

Purpose:

• Show how to do something
• Provide step-by-step flows
• Demonstrate integration patterns

Rules:

• Assume concepts are known
• Be explicit about trade-offs
• Avoid magic shortcuts

Guides teach execution, not theory.

4. Reference

Purpose:

• Define exact behavior
• Specify API contracts
• Eliminate ambiguity

Rules:

• Precise language
• No narrative
• No opinion

Reference defines reality.

5. FAQ

Purpose:

• Address misunderstandings
• Explain trade-offs
• Reframe incorrect assumptions

Rules:

• Short, direct answers
• No repetition of reference content
• Link out for depth

FAQ reduces friction.

6. Roadmap

Purpose:

• Define constraints on future change
• Clarify non-goals and intent
• Set expectations

Rules:

• Conservative language
• No promises
• No timelines

Roadmap defines boundaries, not schedules.

Writing Style Guidelines

Plumego documentation follows a consistent tone.

Be Explicit

Avoid:

• “Usually”
• “Often”
• “Typically”
• “Might”
• “Should work”

Prefer:

• “Must”
• “Will”
• “Does not”
• “Is guaranteed”
• “Is not supported”

Ambiguity is treated as a bug.

Be Honest About Trade-Offs

Do not hide downsides.

If something:

• Is harder
• Requires discipline
• Is intentionally missing

Say so clearly.

Plumego documentation values trust over persuasion.

Avoid Marketing Language

Do not use:

• “Powerful”
• “Flexible”
• “Elegant”
• “Best-in-class”
• “Revolutionary”

Explain behavior, not feelings.

Prefer Constraints Over Capabilities

Good documentation explains:

• What is forbidden
• What is unsupported
• What will not be added

Constraints shape understanding better than feature lists.

Documentation and Versioning

Documentation is versioned with code.

Rules:

• Reference reflects current behavior only
• Deprecated behavior is clearly marked
• Removed behavior is documented in migration guides
• No “future tense” in reference docs

If behavior is not released, it is not documented.

Documentation Review Criteria

Documentation changes are reviewed for:

• Accuracy
• Clarity
• Consistency with principles
• Correct placement in hierarchy
• Absence of hidden assumptions

Documentation PRs can be rejected
even if technically correct,
if they introduce confusion.

Common Documentation Mistakes

1. Explaining How Before Why

Readers need mental models before procedures.

If a guide references a concept
that is not explained elsewhere,
the documentation hierarchy is broken.

2. Mixing Layers

Do not:

• Put API details in Concepts
• Put tutorials in Reference
• Put opinions in Architecture

Each layer has a purpose.

3. Writing Around Uncertainty

If behavior is unclear,
clarify the behavior — do not hedge the language.

Uncertainty should be resolved,
not documented.

4. Documenting Implementation Details

Unless explicitly part of the contract,
implementation details belong in code comments,
not user-facing documentation.

Documentation as Design Feedback

Writing documentation often reveals:

• Unclear abstractions
• Leaky boundaries
• Hidden behavior
• Inconsistent terminology

If something is hard to document clearly,
the design likely needs improvement.

Documentation is a design tool.

Non-Code Contributions Are First-Class

You can contribute meaningfully by:

• Improving explanations
• Clarifying boundaries
• Identifying ambiguity
• Reducing cognitive load
• Aligning docs with real usage

Many of Plumego’s best improvements
come from documentation-driven insight.

Summary

In Plumego:

• Documentation defines intent
• Intent constrains code
• Clarity beats completeness
• Honesty beats convenience

If you change Plumego,
you are changing a promise.

Write documentation accordingly.

Related Contributing Pages

• Code Structure — where changes belong
• Decision Process — how changes are evaluated
• Workflow — how documentation changes are reviewed

Good documentation does not explain everything.

It explains exactly what must be understood.