lmxopcua/StyleGuide.md

# Documentation Style Guide

This guide defines writing conventions and formatting rules for all ScadaBridge 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 `ScadaGatewayActor` routes messages to the appropriate `ScadaClientActor` based on the client ID in the message.

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

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

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

**Good:**
> Health checks use a 5-second timeout because actors under heavy load may take several seconds to respond, but longer delays indicate a real problem.

**Avoid:**
> Health checks use a 5-second timeout.

### Use Present Tense

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

**Good:**
> The actor validates the message before processing.

**Avoid:**
> The actor will validate the message before processing.

### 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:
- `Overview.md`
- `HealthChecks.md`
- `StateMachines.md`
- `SignalR.md`

### Headings

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

```markdown
# Actor Health Checks

## Configuration Options

### Setting the timeout

#### Default values
```

### Code Blocks

Always specify the language:

````markdown
```csharp
public class MyActor : ReceiveActor { }
```

```json
{
  "Setting": "value"
}
```

```bash
dotnet build
```
````

Supported languages: `csharp`, `json`, `bash`, `xml`, `sql`, `yaml`, `html`, `css`, `javascript`

### 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 class TemplateInstanceActor : ReceiveActor
{
    public TemplateInstanceActor(TemplateInstanceConfig config)
    {
        Receive<StartProcessing>(Handle);
    }
}

// Avoid - orphaned snippet
Receive<StartProcessing>(Handle);
```

**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 |
|--------|---------|-------------|
| `Timeout` | `5000` | Milliseconds to wait |
| `RetryCount` | `3` | Number of retry attempts |
```

### Inline Code

Use backticks for:
- Class names: `ScadaGatewayActor`
- Method names: `HandleMessage()`
- File names: `appsettings.json`
- Configuration keys: `ScadaBridge:Timeout`
- Command-line commands: `dotnet build`

### Links

Use relative paths for internal documentation:
```markdown
[See the Actors guide](../Akka/Actors.md)
[Configuration options](./Configuration.md)
```

Use descriptive link text:
```markdown
<!-- Good -->
See the [Actor Health Checks](../Akka/HealthChecks.md) documentation.

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

## Structure Conventions

### Document Opening

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

```markdown
# Actor Health Checks

Health checks monitor actor responsiveness and report status to the ASP.NET Core health check system.
```

### 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
## Message Handling

Actors process messages using `Receive<T>` handlers:

```csharp
Receive<MyMessage>(msg => HandleMyMessage(msg));
```

Each handler processes one message type...
```

### Related Documentation Section

End each document with links to related topics:

```markdown
## Related Documentation

- [Actor Patterns](./Patterns.md)
- [Health Checks](../Operations/HealthChecks.md)
- [Configuration](../Configuration/Akka.md)
```

## Naming Conventions

### Match Code Exactly

Use the exact names from source code:
- `TemplateInstanceActor` not "Template Instance Actor"
- `ScadaGatewayActor` not "SCADA Gateway Actor"
- `IRequiredActor<T>` not "required actor interface"

### Acronyms

Spell out on first use, then use acronym:
> OPC Unified Architecture (OPC UA) provides industrial communication standards. OPC UA servers expose...

Common acronyms that don't need expansion:
- API
- JSON
- SQL
- HTTP/HTTPS
- REST
- JWT
- UI

### File Paths

Use forward slashes and backticks:
- `src/Infrastructure/Akka/Actors/`
- `appsettings.json`
- `Documentation/Akka/Overview.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 an `IActorRef` for the gateway actor, which must be resolved before actor creation.
```

### Don't Duplicate Source Code Comments

If code has good comments, reference the file rather than copying:
> See `ScadaGatewayActor.cs` lines 45-60 for the message routing logic.

### 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
- Entity Framework basics
- ASP.NET Core middleware pipeline