natsdotnet/documentation_rules.md

Documentation Rules

This document defines the documentation system for the NATS .NET server project. It provides guidelines for generating, updating, and maintaining project documentation.

The documentation is intended for internal team reference — explaining what the system is, how it works, how to extend it, and how to debug it.

Folder Structure

Documentation/
├── Instructions/              # Guidelines for LLMs (meta-documentation)
│   └── (this file serves as the single instructions reference)
│
├── GettingStarted/            # Onboarding, prerequisites, first run
├── Protocol/                  # Wire protocol, parser, command types
├── Subscriptions/             # SubList trie, subject matching, wildcards
├── Server/                    # NatsServer orchestrator, NatsClient handler
├── Configuration/             # NatsOptions, appsettings, CLI arguments
├── Operations/                # Deployment, monitoring, health checks, troubleshooting
└── Plans/                     # Design documents and implementation plans

Future module folders (add as modules are ported):

├── Authentication/            # Auth mechanisms, NKeys, JWT, accounts
├── Clustering/                # Routes, gateways, leaf nodes
├── JetStream/                 # Streams, consumers, storage, RAFT
├── Monitoring/                # HTTP endpoints (/varz, /connz, etc.)
├── WebSocket/                 # WebSocket transport
└── TLS/                       # TLS configuration and setup

---

Style Guide

Tone and Voice

• Technical and direct — no marketing language. Avoid "powerful", "robust", "seamless", "blazing fast".
• Assume the reader is a .NET developer — don't explain dependency injection, async/await, or LINQ basics.
• Explain "why" not just "what" — document reasoning behind patterns and decisions.
• Use present tense — "The parser reads..." not "The parser will read..."

Formatting Rules

Aspect	Convention
File names	PascalCase.md
H1 (#)	Document title only, Title Case
H2 (##)	Major sections, Title Case
H3+ (###)	Subsections, Sentence case
Code blocks	Always specify language (csharp, json, bash, xml)
Code snippets	5-25 lines typical; include class/method context
Cross-references	Relative paths: [See SubList](../Subscriptions/SubList.md)
Inline code	Backticks for code refs: NatsServer, SubList.Match(), NatsOptions
Lists	Bullets for unordered, numbers for sequential steps
Tables	For structured reference (config options, command formats)

Naming Conventions

• Match code terminology exactly: SubList not "Subject List", NatsClient not "NATS Client Handler"
• Use backticks for all code references: NatsParser, appsettings.json, dotnet test
• Spell out acronyms on first use: "NATS Adaptive Edge Messaging (NATS)" — common acronyms that don't need expansion: API, JSON, TCP, HTTP, TLS, JWT

Code Snippet Guidelines

Do:

• Copy snippets from actual source files
• Include enough context (class name, method signature)
• Specify the language in code blocks
• Show 5-25 line examples

// Good — shows class context
public sealed class NatsServer : IMessageRouter, ISubListAccess, IDisposable
{
    public async Task StartAsync(CancellationToken ct)
    {
        _listener = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp);
        _listener.Bind(new IPEndPoint(IPAddress.Parse(_options.Host), _options.Port));
        _listener.Listen(128);
    }
}

Don't:

• Invent example code that doesn't exist in the codebase
• Include 100+ line dumps without explanation
• Use pseudocode when real code is available
• Omit the language specifier on code blocks

Structure Conventions

Every documentation file must include:

1. Title and purpose — H1 heading with 1-2 sentence description
2. Key concepts — if the topic requires background understanding
3. Code examples — embedded snippets from actual codebase
4. Configuration — if the component has configurable options
5. Related documentation — links to related topics

Organize content from general to specific:

1. Overview/introduction
2. Key concepts
3. Basic usage
4. Advanced usage / internals
5. Configuration
6. Troubleshooting
7. Related documentation

End each document with:

## Related Documentation

- [Related Topic](../Component/Topic.md)

What to Avoid

• Don't document the obvious (e.g., "The constructor creates a new instance")
• Don't duplicate source code comments — reference the file instead
• Don't include temporary information (dates, version numbers, "coming soon")
• Don't over-explain .NET basics

---

Generating Documentation

Document Types

Each component folder should contain these standard files:

File	Purpose
Overview.md	What the component does, key concepts, architecture
Development.md	How to add/modify features, patterns to follow
Configuration.md	All configurable options with defaults and examples
Troubleshooting.md	Common issues, error messages, debugging steps

Create additional topic-specific files as needed (e.g., Protocol/Parser.md, Subscriptions/SubList.md).

Generation Process

1. Identify scope — which component folder does this belong to? (See Component Map below)
2. Read source code — understand the current implementation, identify key classes/methods/patterns, note configuration options
3. Check existing documentation — avoid duplication, cross-reference rather than repeat
4. Write documentation — follow the style guide, use real code snippets
5. Verify accuracy — confirm snippets match source, verify file paths and class names, test commands

Creating New Component Folders

1. Create the folder under Documentation/
2. Add at minimum Overview.md
3. Add other standard files as content warrants
4. Update the Component Map section below
5. Add cross-references from related documentation

---

Updating Documentation

Update Triggers

Code Change	Update These Docs
New protocol command	Protocol/ relevant file
Parser modified	Protocol/Parser.md
Subject matching changed	Subscriptions/SubjectMatch.md
SubList trie modified	Subscriptions/SubList.md
New subscription type	Subscriptions/Overview.md
NatsServer changed	Server/Overview.md
NatsClient changed	Server/Client.md
Config option added/removed	Component's Configuration.md
NatsOptions changed	Configuration/Overview.md
Host startup changed	Operations/Deployment.md + Configuration/
New test patterns	Corresponding component docs
Auth mechanism added	Authentication/ (create if needed)
Clustering added	Clustering/ (create if needed)

Update Process

1. Identify affected documentation — use the Component Map to determine which docs need updating
2. Read current documentation — understand existing structure before making changes
3. Make targeted updates — only modify sections affected by the code change; don't rewrite unaffected sections
4. Update code snippets — if the code change affects documented examples, update them to match
5. Update cross-references — add links to newly related docs, remove links to deleted content
6. Add verification comment — at the bottom: <!-- Last verified against codebase: YYYY-MM-DD -->

Deletion Handling

• When code is removed, remove corresponding doc sections
• When code is renamed, update all references (docs, snippets, cross-reference links)
• If an entire feature is removed, delete the doc file and update any index/overview docs
• Search all docs for links to removed content

What Not to Update

• Don't reformat documentation that wasn't affected by the code change
• Don't update examples that still work correctly
• Don't add new content unrelated to the code change
• Don't change writing style in unaffected sections

---

Component Map

Source to Documentation Mapping

Source Path	Documentation Folder
src/NATS.Server/Protocol/NatsParser.cs	Protocol/
src/NATS.Server/Protocol/NatsProtocol.cs	Protocol/
src/NATS.Server/Subscriptions/SubList.cs	Subscriptions/
src/NATS.Server/Subscriptions/SubjectMatch.cs	Subscriptions/
src/NATS.Server/Subscriptions/Subscription.cs	Subscriptions/
src/NATS.Server/Subscriptions/SubListResult.cs	Subscriptions/
src/NATS.Server/NatsServer.cs	Server/
src/NATS.Server/NatsClient.cs	Server/
src/NATS.Server/NatsOptions.cs	Configuration/
src/NATS.Server.Host/Program.cs	Operations/ and Configuration/
tests/NATS.Server.Tests/	Document in corresponding component
golang/nats-server/server/	Reference material (not documented separately)

Component Details

Protocol/

Documents the wire protocol and parser.

Source paths:

• src/NATS.Server/Protocol/NatsParser.cs — state machine parser
• src/NATS.Server/Protocol/NatsProtocol.cs — constants, ServerInfo, ClientOptions

Typical files:

• Overview.md — NATS protocol format, command types, wire format
• Parser.md — Parser implementation, TryParse flow, state machine
• Commands.md — Individual command formats (PUB, SUB, UNSUB, MSG, etc.)

Subscriptions/

Documents subject matching and the subscription trie.

Source paths:

• src/NATS.Server/Subscriptions/SubList.cs — trie + cache
• src/NATS.Server/Subscriptions/SubjectMatch.cs — validation and wildcard matching
• src/NATS.Server/Subscriptions/Subscription.cs — subscription model
• src/NATS.Server/Subscriptions/SubListResult.cs — match result container

Typical files:

• Overview.md — Subject namespace, wildcard rules, queue groups
• SubList.md — Trie internals, cache invalidation, thread safety
• SubjectMatch.md — Validation rules, wildcard matching algorithm

Server/

Documents the server orchestrator and client connection handler.

Source paths:

• src/NATS.Server/NatsServer.cs — accept loop, message routing
• src/NATS.Server/NatsClient.cs — per-connection read/write, subscription tracking

Typical files:

• Overview.md — Server architecture, connection lifecycle, message flow
• Client.md — Client connection handling, command dispatch, write serialization
• MessageRouting.md — How messages flow from PUB to subscribers

Configuration/

Documents server configuration options.

Source paths:

• src/NATS.Server/NatsOptions.cs — configuration model
• src/NATS.Server.Host/Program.cs — CLI argument parsing, Serilog setup

Typical files:

• Overview.md — All options with defaults and descriptions
• Logging.md — Serilog configuration, log levels, LogContext usage

Operations/

Documents deployment and operational concerns.

Source paths:

• src/NATS.Server.Host/ — host application

Typical files:

• Overview.md — Running the server, CLI arguments
• Deployment.md — Deployment procedures
• Troubleshooting.md — Common issues and debugging

GettingStarted/

Documents onboarding and project overview.

Typical files:

• Setup.md — Prerequisites, building, running
• Architecture.md — System overview, Go reference mapping
• Development.md — Development workflow, testing, contributing

Ambiguous Cases

Code Type	Document In
Logging setup	Configuration/Logging.md
Integration tests	Operations/Testing.md or corresponding component
Shared interfaces (IMessageRouter, ISubListAccess)	Server/Overview.md
Go reference code	Don't document separately; reference in .NET component docs

Adding New Components

When a new module is ported (Authentication, Clustering, JetStream, etc.):

1. Create a new folder under Documentation/
2. Add at minimum Overview.md
3. Add this mapping table entry
4. Update CLAUDE.md documentation index if it has one
5. Cross-reference from related component docs