jdescopingtool/DOCUMENTATION/Instructions/GeneratingDocs.md

Generating Documentation

This guide defines how to create new documentation for the JDE Scoping Tool migration project. Follow these instructions when documenting new features, components, or systems.

Document Types

Each component folder should contain these standard files:

File	Purpose
Overview.md	What the component does, key concepts, architecture diagrams
Development.md	How to add/modify features, patterns to follow, best practices
Configuration.md	All configurable options with defaults and examples
Troubleshooting.md	Common issues, error messages, debugging steps

Create additional topic-specific files as needed (e.g., Search/Criteria.md, DataSync/JDE.md, Export/Excel.md).

Generation Process

Step 1: Identify Scope

Determine what you're documenting:

• Which component folder does this belong to? (See ComponentMap.md)
• Is this a new document or an addition to an existing one?
• What source files contain the implementation?

Step 2: Read Source Code

Before writing any documentation:

1. Read the relevant source files thoroughly
2. Understand the current implementation, not assumptions
3. Identify key classes, methods, and patterns
4. Note any configuration options or environment variables
5. Look for existing code comments that explain "why"

Step 3: Check Existing Documentation

Avoid duplication:

1. Search DOCUMENTATION/ for related content
2. If similar content exists, update it rather than creating new
3. Cross-reference related docs rather than repeating information

Step 4: Write Documentation

Structure your document following the StyleGuide.md:

# Component/Feature Name

Brief 1-2 sentence description of what this is and why it exists.

## Key Concepts

Explain the important ideas a developer needs to understand.

## Usage

### Basic Example

```csharp
// Code snippet from actual source

Common Patterns

Describe typical usage patterns with code examples.

Configuration

Option	Default	Description
OptionName	value	What it does

Related Documentation

• Related Topic

### Step 5: Verify Accuracy

Before finalizing:
1. Confirm all code snippets match actual source code
2. Verify file paths and class names are correct
3. Test any commands or configuration examples
4. Ensure cross-references point to existing files

## Required Sections

Every documentation file must include:

1. **Title and Purpose** - H1 heading with 1-2 sentence description
2. **Key Concepts** - If the topic requires background understanding
3. **Code Examples** - Embedded snippets from actual codebase
4. **Configuration** - If the component has configurable options
5. **Related Documentation** - Links to related topics

## Code Snippet Guidelines

### Do

- Copy snippets from actual source files
- Include enough context (class name, method signature)
- Show typical 5-25 line examples
- Specify the language in code blocks

```csharp
public class SearchProcessor : BackgroundService
{
    private readonly ISearchRepository _searchRepository;

    public SearchProcessor(ISearchRepository searchRepository)
    {
        _searchRepository = searchRepository;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await ProcessQueuedSearchesAsync(stoppingToken);
    }
}

Don't

• Invent example code that doesn't exist in the codebase
• Include 100+ line dumps without explanation
• Use pseudocode when real code is available
• Omit the language specifier on code blocks

File Naming

• Use PascalCase.md for all documentation files
• Match the concept being documented: Actors.md, Migrations.md, SignalR.md
• For multi-word topics: HealthChecks.md, StateMachines.md
• Avoid abbreviations unless universally understood: API.md is fine, TIA.md is not

Creating New Component Folders

When documenting a new system component:

1. Create the folder under DOCUMENTATION/
2. Add at minimum Overview.md
3. Add other standard files as content warrants
4. Update ComponentMap.md with the new mapping
5. Add cross-references from related documentation