jdescopingtool/DOCUMENTATION/Instructions/UpdatingDocs.md

# 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