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

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

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

Links

Use relative paths for internal documentation:

[See the Search guide](../Search/Overview.md)
[Configuration options](./Configuration.md)

Use descriptive link text:

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

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

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

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