mxaccessgw/StyleGuide.md

# Documentation Style Guide

This guide defines writing conventions and formatting rules for all MXAccess
Gateway (`mxaccessgw`) documentation.

## Tone and Voice

### Be Technical and Direct

Write for developers who are familiar with .NET. Don't explain basic concepts
like dependency injection or async/await unless they're used in an unusual way.

**Good:**
> The `SessionManager` launches one worker per session and tracks it through the
> session state machine.

**Avoid:**
> The SessionManager is a really powerful component that helps manage all your
> MXAccess connections efficiently!

### Explain "Why" Not Just "What"

Document the reasoning behind patterns and decisions, not just the mechanics.

**Good:**
> The worker pumps Windows messages on its STA thread because a plain blocking
> queue does not let MXAccess COM events deliver.

**Avoid:**
> The worker pumps Windows messages on its STA thread.

### Use Present Tense

Describe what the code does, not what it will do.

**Good:**
> The gateway terminates orphaned workers on startup.

**Avoid:**
> The gateway will terminate orphaned workers on startup.

### No Marketing Language

This is internal technical documentation. Avoid superlatives and promotional
language.

**Avoid:** "powerful", "robust", "cutting-edge", "seamless", "blazing fast"

## Formatting Rules

### File Names

Use `PascalCase.md` for all documentation files:
- `Sessions.md`
- `GatewayConfiguration.md`
- `WorkerSta.md`
- `Diagnostics.md`

### Headings

- **H1 (`#`):** Document title only, Title Case
- **H2 (`##`):** Major sections, Title Case
- **H3 (`###`):** Subsections, Sentence case
- **H4+ (`####`):** Rarely needed, Sentence case

```markdown
# Gateway Configuration

## Session Options

### Setting the lease timeout

#### Default values
```

### Code Blocks

Always specify the language:

````markdown
```csharp
public sealed class GatewaySession { }
```

```json
{
  "MxGateway": { "Sessions": { "MaxConcurrent": 8 } }
}
```

```powershell
dotnet build src/ZB.MOM.WW.MxGateway.slnx
```
````

Supported languages: `csharp`, `json`, `bash`, `powershell`, `xml`, `sql`,
`text`, `rust`, `python`, `go`, `proto`, `html`, `css`, `toml`.

### Code Snippets

**Length:** 5-25 lines is typical. Shorter for simple concepts, longer for
complete examples.

**Context:** Include enough to understand where the code lives:

```csharp
// Good - shows class context
public sealed class GatewaySession
{
    public GatewaySession(SessionId sessionId, WorkerPipeSession pipe)
    {
        _sessionId = sessionId;
        _pipe = pipe;
    }
}

// Avoid - orphaned snippet
_pipe = pipe;
```

**Accuracy:** Only use code that exists in the codebase. Never invent examples.

### Lists

Use bullet points for unordered items:
```markdown
- First item
- Second item
- Third item
```

Use numbers for sequential steps:
```markdown
1. Do this first
2. Then do this
3. Finally do this
```

### Tables

Use tables for structured reference information:

```markdown
| Option | Default | Description |
|--------|---------|-------------|
| `MaxConcurrent` | `8` | Maximum simultaneous sessions |
| `LeaseTimeoutSeconds` | `60` | Idle lease before sweep |
```

### Inline Code

Use backticks for:
- Class names: `SessionManager`
- Method names: `KillWorkerAsync()`
- File names: `appsettings.json`
- Configuration keys: `MxGateway:Sessions:MaxConcurrent`
- Command-line commands: `dotnet build`

### Links

Use relative paths for internal documentation:
```markdown
[See the architecture overview](./gateway.md)
[Configuration options](./docs/GatewayConfiguration.md)
```

Use descriptive link text:
```markdown
<!-- Good -->
See the [Gateway Configuration](./docs/GatewayConfiguration.md) documentation.

<!-- Avoid -->
See [here](./docs/GatewayConfiguration.md) for more.
```

## Structure Conventions

### Document Opening

Every document starts with:
1. H1 title
2. 1-2 sentence description of purpose

```markdown
# Worker STA Thread

The worker owns one MXAccess COM instance on a dedicated STA thread and pumps
Windows messages so MXAccess events deliver.
```

### Section Organization

Organize content from general to specific:
1. Overview/introduction
2. Key concepts (if needed)
3. Basic usage
4. Advanced usage
5. Configuration
6. Troubleshooting
7. Related documentation

### Code Example Placement

Place code examples immediately after the concept they illustrate:

```markdown
## Session Close

The gateway closes a session by killing its worker behind the close gate:

```csharp
await session.KillWorkerWithCloseGateAsync(cancellationToken);
```

The close gate serializes concurrent close attempts...
```

### Related Documentation Section

End each document with links to related topics:

```markdown
## Related Documentation

- [Sessions](./docs/Sessions.md)
- [Worker STA Thread](./docs/WorkerSta.md)
- [Gateway Configuration](./docs/GatewayConfiguration.md)
```

## Naming Conventions

### Match Code Exactly

Use the exact names from source code:
- `MxStatusProxy` not "MX status proxy"
- `SessionManager` not "session manager"
- `OrphanWorkerTerminator` not "orphan worker terminator"

### Acronyms

Spell out on first use, then use acronym:
> Single-threaded apartment (STA) threads serialize COM calls. STA message
> pumping lets MXAccess events deliver...

Common acronyms that don't need expansion:
- API
- JSON
- SQL
- HTTP/HTTPS
- COM
- gRPC
- IPC
- STA
- UI

### File Paths

Use forward slashes and backticks:
- `src/ZB.MOM.WW.MxGateway.Server/`
- `appsettings.json`
- `docs/GatewayConfiguration.md`

## What to Avoid

### Don't Document the Obvious

```markdown
<!-- Avoid -->
## Constructor

The constructor creates a new instance of the class.

<!-- Better - only document if there's something notable -->
## Constructor

The constructor accepts a `WorkerPipeSession`, which must be connected before
the session transitions out of `Handshaking`.
```

### Don't Duplicate Source Code Comments

If code has good comments, reference the file rather than copying:
> See `SessionManager.cs` for the open-failure rollback order.

### Don't Include Temporary Information

Avoid dates, version numbers, or "coming soon" notes that will become stale.

### Don't Over-Explain .NET Basics

Assume readers know:
- Dependency injection
- async/await
- LINQ
- ASP.NET Core middleware pipeline
- gRPC service basics

## Related Documentation

- [Architecture overview](./gateway.md)
- [Gateway Configuration](./docs/GatewayConfiguration.md)
- [C# Style Guide](./docs/style-guides/CSharpStyleGuide.md)
- [Go Style Guide](./docs/style-guides/GoStyleGuide.md), [Java Style Guide](./docs/style-guides/JavaStyleGuide.md), [Python Style Guide](./docs/style-guides/PythonStyleGuide.md), [Rust Style Guide](./docs/style-guides/RustStyleGuide.md), [Protobuf Style Guide](./docs/style-guides/ProtobufStyleGuide.md)