Joseph Doherty
26ff8d9b4f
Set up repository with legacy .NET Framework 4.8 source (OLD/), new .NET 10 Blazor solution (NEW/), OpenSpec specifications, documentation, and project configuration.
146 lines
4.2 KiB
Markdown
146 lines
4.2 KiB
Markdown
# 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](./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](./StyleGuide.md):
|
|
|
|
```markdown
|
|
# 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](../OtherComponent/RelatedTopic.md)
|
|
```
|
|
|
|
### 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](./ComponentMap.md) with the new mapping
|
|
5. Add cross-references from related documentation
|