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

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