Initial commit: JDE Scoping Tool migration project
Set up repository with legacy .NET Framework 4.8 source (OLD/), new .NET 10 Blazor solution (NEW/), OpenSpec specifications, documentation, and project configuration.
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,249 @@
|
||||
# Component Map
|
||||
|
||||
This document maps source code locations to their corresponding documentation folders. Use this to determine where documentation should live.
|
||||
|
||||
## Project Structure
|
||||
|
||||
This is a migration project with two main code areas:
|
||||
|
||||
```
|
||||
JdeScopingTool/
|
||||
├── OLD/ # Legacy .NET Framework 4.8 (read-only reference)
|
||||
├── NEW/ # New .NET 10 solution (build target)
|
||||
├── SPECS/ # OpenSpec specifications
|
||||
└── DOCUMENTATION/ # Project documentation
|
||||
```
|
||||
|
||||
## Source to Documentation Mapping
|
||||
|
||||
### Legacy Code (OLD/)
|
||||
|
||||
| Source Path | Documentation Folder |
|
||||
|-------------|---------------------|
|
||||
| `OLD/WebInterface/` | `LegacyReference/WebInterface/` |
|
||||
| `OLD/WebInterface/Controllers/` | `LegacyReference/WebInterface/Controllers.md` |
|
||||
| `OLD/WebInterface/Hubs/` | `LegacyReference/WebInterface/SignalR.md` |
|
||||
| `OLD/WorkerService/` | `LegacyReference/WorkerService/` |
|
||||
| `OLD/WorkerService/Process/` | `LegacyReference/WorkerService/Processing.md` |
|
||||
| `OLD/DataModel/` (Commons) | `LegacyReference/DataModel/` |
|
||||
| `OLD/DataModel/Process/JDE*.cs` | `DataSync/JDE.md` |
|
||||
| `OLD/DataModel/Process/CMS*.cs` | `DataSync/CMS.md` |
|
||||
| `OLD/DataModel/Process/LotFinderDB*.cs` | `Database/LocalCache.md` |
|
||||
| `OLD/DataModel/Models/` | `Database/Entities.md` |
|
||||
| `OLD/Database/` | `Database/Schema.md` |
|
||||
|
||||
### New Code (NEW/)
|
||||
|
||||
| Source Path | Documentation Folder |
|
||||
|-------------|---------------------|
|
||||
| `NEW/src/` | Component-specific folders |
|
||||
| `NEW/src/Web/Controllers/` | `API/Endpoints.md` |
|
||||
| `NEW/src/Web/Hubs/` | `API/SignalR.md` |
|
||||
| `NEW/src/Web/Client/` (Blazor) | `WebClient/` |
|
||||
| `NEW/src/Services/` | `BackgroundServices/` |
|
||||
| `NEW/src/Core/Models/` | `Database/Entities.md` |
|
||||
| `NEW/src/Core/Interfaces/` | Document in implementing component |
|
||||
| `NEW/src/Infrastructure/` | Component-specific folders |
|
||||
| `NEW/appsettings*.json` | `Configuration/` |
|
||||
| `NEW/tests/` | Document in corresponding component |
|
||||
|
||||
## Documentation Folder Structure
|
||||
|
||||
```
|
||||
DOCUMENTATION/
|
||||
├── Instructions/ # This folder - documentation guidelines
|
||||
├── GettingStarted/ # Onboarding, prerequisites, architecture overview
|
||||
├── LegacyReference/ # Documentation of the OLD codebase for migration reference
|
||||
│ ├── WebInterface/ # ASP.NET MVC web application
|
||||
│ ├── WorkerService/ # Windows service (Topshelf)
|
||||
│ └── DataModel/ # Shared library (Commons.csproj)
|
||||
├── Search/ # Search functionality
|
||||
├── DataSync/ # JDE/CMS data synchronization
|
||||
├── Database/ # SQL Server cache, entities, schema
|
||||
├── API/ # REST endpoints, SignalR
|
||||
├── WebClient/ # Blazor WASM UI
|
||||
├── Export/ # Excel generation
|
||||
├── Authentication/ # LDAP authentication
|
||||
├── BackgroundServices/ # Background processing
|
||||
├── Configuration/ # appsettings, connection strings
|
||||
└── Operations/ # Deployment, monitoring
|
||||
```
|
||||
|
||||
## Component Details
|
||||
|
||||
### Search/
|
||||
|
||||
Documents the search functionality.
|
||||
|
||||
**Source paths (Legacy):**
|
||||
- `OLD/DataModel/Models/Search*.cs` - Search models
|
||||
- `OLD/DataModel/ViewModels/Search*.cs` - Search view models
|
||||
- `OLD/WebInterface/Controllers/SearchController.cs` - Search API
|
||||
- `OLD/WorkerService/Process/WorkProcessor.cs` - Search execution
|
||||
|
||||
**Source paths (New):**
|
||||
- `NEW/src/Core/Models/Search*.cs` - Search models
|
||||
- `NEW/src/Web/Controllers/SearchController.cs` - Search API
|
||||
- `NEW/src/Services/SearchProcessor.cs` - Search execution
|
||||
|
||||
**Typical files:**
|
||||
- `Overview.md` - Search system architecture
|
||||
- `Criteria.md` - Search criteria model and options
|
||||
- `Execution.md` - How searches are processed
|
||||
- `Results.md` - Result storage and retrieval
|
||||
|
||||
### DataSync/
|
||||
|
||||
Documents data synchronization from enterprise systems.
|
||||
|
||||
**Source paths (Legacy):**
|
||||
- `OLD/DataModel/Process/JDE*.cs` - JDE Oracle queries
|
||||
- `OLD/DataModel/Process/CMS*.cs` - CMS Sybase queries
|
||||
- `OLD/WorkerService/Process/UpdateProcessor.cs` - Sync orchestration
|
||||
- `OLD/WorkerService/dsconfig/*.json` - Data source configs
|
||||
|
||||
**Source paths (New):**
|
||||
- `NEW/src/Infrastructure/DataSync/` - Data sync services
|
||||
- `NEW/src/Infrastructure/DataSync/JDE/` - JDE adapter
|
||||
- `NEW/src/Infrastructure/DataSync/CMS/` - CMS adapter
|
||||
|
||||
**Typical files:**
|
||||
- `Overview.md` - Data sync architecture
|
||||
- `JDE.md` - JD Edwards (Oracle) integration
|
||||
- `CMS.md` - CMS (Sybase) integration
|
||||
- `Scheduling.md` - Mass/daily/hourly sync schedules
|
||||
- `Configuration.md` - Data source configuration
|
||||
|
||||
### Database/
|
||||
|
||||
Documents the SQL Server cache database.
|
||||
|
||||
**Source paths (Legacy):**
|
||||
- `OLD/DataModel/Process/LotFinderDB*.cs` - SQL Server access
|
||||
- `OLD/DataModel/Models/` - Entity definitions
|
||||
- `OLD/Database/` - SQL Server database project
|
||||
|
||||
**Source paths (New):**
|
||||
- `NEW/src/Infrastructure/Persistence/` - EF Core implementation
|
||||
- `NEW/src/Core/Models/` - Entity definitions
|
||||
|
||||
**Typical files:**
|
||||
- `Overview.md` - Database architecture
|
||||
- `Entities.md` - Entity documentation
|
||||
- `LocalCache.md` - Cached data tables
|
||||
- `Schema.md` - Database schema reference
|
||||
|
||||
### API/
|
||||
|
||||
Documents the REST API and real-time communication.
|
||||
|
||||
**Source paths (Legacy):**
|
||||
- `OLD/WebInterface/Controllers/` - MVC controllers
|
||||
- `OLD/WebInterface/Hubs/StatusHub.cs` - SignalR hub
|
||||
|
||||
**Source paths (New):**
|
||||
- `NEW/src/Web/Controllers/` - API controllers
|
||||
- `NEW/src/Web/Hubs/` - SignalR hubs
|
||||
|
||||
**Typical files:**
|
||||
- `Overview.md` - API architecture
|
||||
- `Endpoints.md` - Endpoint reference
|
||||
- `SignalR.md` - Real-time status updates
|
||||
- `Authentication.md` - JWT/LDAP auth
|
||||
|
||||
### WebClient/
|
||||
|
||||
Documents the Blazor WASM frontend.
|
||||
|
||||
**Source paths (New):**
|
||||
- `NEW/src/Web/Client/Pages/` - Page components
|
||||
- `NEW/src/Web/Client/Components/` - Reusable components
|
||||
- `NEW/src/Web/Client/Services/` - Client services
|
||||
|
||||
**Typical files:**
|
||||
- `Overview.md` - Frontend architecture
|
||||
- `Components.md` - Component documentation
|
||||
- `SearchUI.md` - Search interface
|
||||
- `State.md` - State management
|
||||
|
||||
### Export/
|
||||
|
||||
Documents Excel export functionality.
|
||||
|
||||
**Source paths (Legacy):**
|
||||
- `OLD/WorkerService/Process/ExcelWriter.cs` - EPPlus generation
|
||||
- `OLD/WorkerService/Templates/QueryTemplate.cs` - Query templates
|
||||
|
||||
**Source paths (New):**
|
||||
- `NEW/src/Services/ExcelExporter.cs` - Excel generation
|
||||
|
||||
**Typical files:**
|
||||
- `Overview.md` - Export architecture
|
||||
- `Excel.md` - Excel generation details
|
||||
- `Templates.md` - Export templates
|
||||
|
||||
### Authentication/
|
||||
|
||||
Documents LDAP authentication.
|
||||
|
||||
**Source paths (Legacy):**
|
||||
- `OLD/WebInterface/Controllers/AccountController.cs` - Login/logout
|
||||
- `OLD/DataModel/Config.cs` - LDAP configuration
|
||||
|
||||
**Source paths (New):**
|
||||
- `NEW/src/Infrastructure/Authentication/` - Auth services
|
||||
|
||||
**Typical files:**
|
||||
- `Overview.md` - Authentication architecture
|
||||
- `LDAP.md` - LDAP integration details
|
||||
- `Configuration.md` - Auth configuration
|
||||
|
||||
### BackgroundServices/
|
||||
|
||||
Documents background processing.
|
||||
|
||||
**Source paths (Legacy):**
|
||||
- `OLD/WorkerService/` - Topshelf Windows service
|
||||
- `OLD/WorkerService/Process/WorkProcessor.cs` - Main work loop
|
||||
|
||||
**Source paths (New):**
|
||||
- `NEW/src/Services/` - BackgroundService implementations
|
||||
|
||||
**Typical files:**
|
||||
- `Overview.md` - Background service architecture
|
||||
- `SearchProcessor.md` - Search queue processing
|
||||
- `DataSyncService.md` - Data synchronization service
|
||||
|
||||
### LegacyReference/
|
||||
|
||||
Documents the legacy codebase for migration reference.
|
||||
|
||||
**Source paths:**
|
||||
- All files under `OLD/`
|
||||
|
||||
**Typical files:**
|
||||
- `WebInterface/Overview.md` - ASP.NET MVC structure
|
||||
- `WorkerService/Overview.md` - Topshelf service structure
|
||||
- `DataModel/Overview.md` - Commons library structure
|
||||
- `MigrationNotes.md` - Patterns to preserve/change
|
||||
|
||||
## Ambiguous Cases
|
||||
|
||||
When code spans multiple components, use these guidelines:
|
||||
|
||||
| Code Type | Document In |
|
||||
|-----------|-------------|
|
||||
| SignalR hubs | `API/SignalR.md` |
|
||||
| SignalR clients | `WebClient/SignalR.md` |
|
||||
| Shared DTOs | Component that "owns" the concept |
|
||||
| Cross-cutting services | Most relevant component |
|
||||
| Legacy patterns | `LegacyReference/` with cross-references |
|
||||
|
||||
## Adding New Components
|
||||
|
||||
When adding a new system component:
|
||||
|
||||
1. Create a new folder under `DOCUMENTATION/`
|
||||
2. Add at minimum `Overview.md`
|
||||
3. Update this mapping table
|
||||
4. Update [GeneratingDocs.md](./GeneratingDocs.md) if new patterns emerge
|
||||
@@ -0,0 +1,145 @@
|
||||
# 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
|
||||
@@ -0,0 +1,282 @@
|
||||
# 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
|
||||
@@ -0,0 +1,156 @@
|
||||
# Updating Documentation
|
||||
|
||||
This guide defines when and how to update existing documentation. Documentation should always reflect the current codebase state.
|
||||
|
||||
## Update Triggers
|
||||
|
||||
When these code changes occur, update the corresponding documentation:
|
||||
|
||||
| Code Change | Update These Docs |
|
||||
|-------------|-------------------|
|
||||
| New API endpoint | `API/Endpoints.md`, update `API/Overview.md` |
|
||||
| API endpoint changed | Corresponding endpoint documentation |
|
||||
| New entity added | `Database/Entities.md` |
|
||||
| Search criteria modified | `Search/Criteria.md` |
|
||||
| New data sync source | `DataSync/` relevant file (JDE, CMS, etc.) |
|
||||
| Data sync logic changed | Corresponding data sync documentation |
|
||||
| Excel export modified | `Export/Excel.md` |
|
||||
| New Blazor component | `WebClient/Components.md` |
|
||||
| SignalR hub changed | `API/SignalR.md` |
|
||||
| Background service modified | `BackgroundServices/` relevant file |
|
||||
| Config option added | Component's `Configuration.md` |
|
||||
| Config option removed | Remove from docs |
|
||||
| Authentication changed | `Authentication/LDAP.md` |
|
||||
| Deployment config changed | `Operations/Deployment.md` |
|
||||
| appsettings changed | `Configuration/` relevant file |
|
||||
|
||||
## Update Process
|
||||
|
||||
### Step 1: Identify Affected Documentation
|
||||
|
||||
Use [ComponentMap.md](./ComponentMap.md) to determine which docs need updating:
|
||||
1. Identify the source files that changed
|
||||
2. Map them to documentation folders
|
||||
3. List all potentially affected documentation files
|
||||
|
||||
### Step 2: Read Current Documentation
|
||||
|
||||
Before making changes:
|
||||
1. Read the entire document you're updating
|
||||
2. Understand the existing structure and flow
|
||||
3. Identify sections that need modification
|
||||
|
||||
### Step 3: Make Targeted Updates
|
||||
|
||||
Keep changes minimal and focused:
|
||||
- Only modify sections affected by the code change
|
||||
- Don't rewrite unaffected sections
|
||||
- Preserve existing explanations that are still accurate
|
||||
- Maintain consistent style with surrounding content
|
||||
|
||||
### Step 4: Update Code Snippets
|
||||
|
||||
If the code change affects documented examples:
|
||||
1. Locate all code snippets that reference the changed code
|
||||
2. Update snippets to match the new implementation
|
||||
3. Verify the updated snippets compile/work correctly
|
||||
|
||||
### Step 5: Update Cross-References
|
||||
|
||||
If the change creates or removes relationships:
|
||||
1. Add links to newly related documentation
|
||||
2. Remove links to deleted content
|
||||
3. Update link text if document titles changed
|
||||
|
||||
### Step 6: Add Verification Comment
|
||||
|
||||
At the bottom of updated documents, add or update:
|
||||
```markdown
|
||||
<!-- Last verified against codebase: YYYY-MM-DD -->
|
||||
```
|
||||
|
||||
## Deletion Handling
|
||||
|
||||
### When Code Is Removed
|
||||
|
||||
1. **Remove corresponding documentation sections**
|
||||
- Delete paragraphs describing removed features
|
||||
- Remove code snippets that no longer apply
|
||||
- Update "Key Concepts" if concepts no longer exist
|
||||
|
||||
2. **Update cross-references**
|
||||
- Search all docs for links to removed content
|
||||
- Either remove the link or redirect to replacement content
|
||||
- Update any "See also" or "Related" sections
|
||||
|
||||
3. **Handle complete feature removal**
|
||||
- If an entire file's subject is removed, delete the file
|
||||
- Update any index or overview docs that referenced it
|
||||
- Check navigation/table of contents if applicable
|
||||
|
||||
### When Code Is Renamed
|
||||
|
||||
1. Update all documentation references to use new names
|
||||
2. Update code snippets with new class/method/variable names
|
||||
3. Rename documentation files if they match the old name
|
||||
4. Update all cross-reference links to renamed files
|
||||
|
||||
## Batch Updates
|
||||
|
||||
When making large-scale code changes:
|
||||
|
||||
1. **List all affected documentation** before starting
|
||||
2. **Update systematically** - one document at a time
|
||||
3. **Verify consistency** across updated documents
|
||||
4. **Check cross-references** after all updates complete
|
||||
|
||||
## Common Update Scenarios
|
||||
|
||||
### Adding a New Search Field
|
||||
|
||||
1. Add entry to `Search/Criteria.md` with:
|
||||
- Field name and data type
|
||||
- Which data source it queries (JDE, CMS, local cache)
|
||||
- How it affects search results
|
||||
- Example usage in search criteria
|
||||
|
||||
2. Update `Search/Overview.md` if the field affects search architecture
|
||||
|
||||
3. Update `Database/Entities.md` if new cache tables are involved
|
||||
|
||||
### Adding a New API Endpoint
|
||||
|
||||
1. Add entry to `API/Endpoints.md` with:
|
||||
- HTTP method and route
|
||||
- Request/response format
|
||||
- Authentication requirements
|
||||
- Example request/response
|
||||
|
||||
2. Update `API/Overview.md` if endpoint represents new functionality
|
||||
|
||||
### Adding a New Data Sync Source
|
||||
|
||||
1. Add entry to `DataSync/` folder with:
|
||||
- Source system details (connection type, schema)
|
||||
- Tables/data being synced
|
||||
- Sync schedule (mass/daily/hourly)
|
||||
- Code snippet showing query patterns
|
||||
|
||||
2. Update `DataSync/Overview.md` with the new source
|
||||
|
||||
3. Update `Database/Entities.md` with any new cache tables
|
||||
|
||||
### Changing Configuration Options
|
||||
|
||||
1. Update the relevant `Configuration.md` file
|
||||
2. If option affects multiple components, update each
|
||||
3. Update any deployment documentation if defaults changed
|
||||
4. Update troubleshooting docs if option helps debug issues
|
||||
|
||||
## What Not to Update
|
||||
|
||||
Avoid unnecessary changes:
|
||||
- Don't reformat documentation that wasn't affected
|
||||
- Don't update examples if they still work correctly
|
||||
- Don't add new content unrelated to the code change
|
||||
- Don't change writing style in unaffected sections
|
||||
Reference in New Issue
Block a user