Documentation

reference/README.md

About Reference Documentation

What's Here

Information-oriented documentation that provides accurate, detailed technical descriptions.

Current reference docs:

  • components/ - Catalog of all components
  • api/ - API endpoint documentation
  • patterns/ - Architectural patterns and best practices
  • configuration/ - Configuration schemas and options
  • tools/ - Development tools and agents
  • build-system.md - MSBuild architecture

What Belongs Here

Reference documentation is descriptive and:

  • Provides technical descriptions
  • Lists all options, parameters, settings
  • Describes structure accurately
  • Is comprehensive and authoritative
  • Answers "what is X?" questions

Examples of good reference docs:

  • "Component API Reference" - All methods, parameters, return types
  • "Configuration Schema" - All config options with types and defaults
  • "MSBuild Properties" - All available properties
  • "Architectural Patterns Catalog" - Complete list of patterns

What Doesn't Belong Here

❌ Step-by-step guides → Use how-to/
❌ Teaching materials → Use tutorials/
❌ Conceptual explanations → Use explanation/
❌ Operational procedures → Use operations/

How to Think About This

Analogy: A dictionary or encyclopedia

  • Reference: "API: interface { method GetById(int id) }"
  • Not reference: "How to call the API" (that's how-to)
  • Not reference: "Why we use interfaces" (that's explanation)
  • Not reference: "Build your first API" (that's tutorial)

Key characteristics:

  • Dry and factual - Just the facts
  • Comprehensive - Everything is documented
  • Consistent structure - Same format throughout
  • Easy to scan - Find information quickly
  • Authoritative - Single source of truth

Writing Guidelines

Structure

Use consistent structure for each type:

API Reference:

## Method: MethodName

**Signature:**
```csharp
Task<ReturnType> MethodName(ParamType param)

Parameters:

  • param (ParamType) - Description

Returns:

  • ReturnType - Description

Exceptions:

  • ExceptionType - When thrown

**Configuration Reference:**
```markdown
## Setting: SettingName

**Type:** `string`
**Default:** `"value"`
**Required:** Yes/No

Description of what this setting does.

**Example:**
```json
{
  "SettingName": "value"
}


### Style
- Be precise and technical
- Use consistent terminology
- Omit unnecessary words
- Format for scanning (tables, lists)
- Include all details
- Keep it current

## Organization

Reference docs are organized by **what you're looking up**:

- **`components/`** - Component catalog and capabilities
- **`api/`** - HTTP endpoints, request/response schemas
- **`patterns/`** - Design patterns, best practices, anti-patterns
- **`configuration/`** - Config files, options, schemas
- **`tools/`** - CLI tools, agents, development tools

## When to Create Reference Docs

Create reference documentation when:
- ✅ You have a complete API or interface to document
- ✅ There are configuration options that need specification
- ✅ You're cataloging components or patterns
- ✅ Information will be looked up frequently

Don't create reference docs when:
- ❌ Teaching how to use something (use tutorial/how-to)
- ❌ Explaining why something exists (use explanation)

## Maintaining Reference Docs

Reference docs should:
- **Stay current** - Update when code changes
- **Be complete** - Document everything, even if obvious
- **Be consistent** - Use same format throughout
- **Be accurate** - Match the actual implementation
- **Link to source** - Reference actual code when possible

Consider **auto-generation** for:
- API documentation (from OpenAPI specs)
- Configuration schemas (from JSON schemas)
- Code documentation (from XML comments)

## Diátaxis Quadrant

**Reference** is:
- **Theoretical** (describing) not practical
- **Information-oriented** not task-oriented
- **Used for work** not for studying
- **Descriptive** not prescriptive

---

**Questions?** See [Documentation Setup](../operations/documentation-setup.md)