jdescopingtool/DOCUMENTATION/Instructions/StyleGuide.md

# Documentation Style Guide

This guide defines writing conventions and formatting rules for all JDE Scoping Tool 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 `SearchProcessor` executes queued searches against the local cache and generates Excel results.

**Avoid:**
> The SearchProcessor is a really powerful component that helps manage all your searches efficiently!

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

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

**Good:**
> Data sync uses a retry pattern with exponential backoff because JDE connections can be temporarily unavailable during peak ERP usage.

**Avoid:**
> Data sync uses retry with backoff.

### 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 SearchProcessor : BackgroundService
{
    public SearchProcessor(ISearchRepository repository)
    {
        _repository = repository;
    }
}

// Avoid - orphaned snippet
_repository = repository;
```

**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: `SearchProcessor`
- Method names: `ProcessQueuedSearches()`
- File names: `appsettings.json`
- Configuration keys: `JdeScoping:ConnectionStrings`
- Command-line commands: `dotnet build`

### Links

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

Use descriptive link text:
```markdown
<!-- Good -->
See the [Data Sync Configuration](../DataSync/Configuration.md) documentation.

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

## Structure Conventions

### Document Opening

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

```markdown
# Search Processor

The search processor handles queued searches, executing queries against the local cache and generating Excel results.
```

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

Searches are executed against the local cache using Dapper:

```csharp
var results = await connection.QueryAsync<WorkOrder>(query, parameters);
```

Each search returns a collection of matching records...
```

### Related Documentation Section

End each document with links to related topics:

```markdown
## Related Documentation

- [Search Criteria](./Criteria.md)
- [Excel Export](../Export/Excel.md)
- [Configuration](../Configuration/Search.md)
```

## Naming Conventions

### Match Code Exactly

Use the exact names from source code:
- `SearchProcessor` not "Search Processor"
- `WorkOrder` not "Work Order"
- `ISearchRepository` not "search repository interface"

### Acronyms

Spell out on first use, then use acronym:
> JD Edwards (JDE) is an Oracle ERP system. JDE stores work order and lot data...

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

### File Paths

Use forward slashes and backticks:
- `NEW/src/Services/SearchProcessor.cs`
- `appsettings.json`
- `DOCUMENTATION/Search/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 `SearchProcessor.cs` lines 45-60 for the search execution 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