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

# Actor Health Checks

## Configuration Options

### Setting the timeout

#### Default values

Code Blocks

Always specify the language:

```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:

// 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:

- First item
- Second item
- Third item

Use numbers for sequential steps:

1. Do this first
2. Then do this
3. Finally do this

Tables

Use tables for structured reference information:

| 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:

[See the Actors guide](../Akka/Actors.md)
[Configuration options](./Configuration.md)

Use descriptive link text:

<!-- 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

# 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:

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

<!-- 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