6.5 KiB

Raw Blame History

Documentation Update Procedures

Post-sprint documentation maintenance.

Overview

This document defines procedures for keeping documentation current after code changes, sprints, and releases. Up-to-date documentation is essential for project maintainability.

Post-Sprint Documentation Updates

Required Updates After Each Sprint

Document Type	Update Required	When
INDEX_MAP.md	If new docs created	After adding docs
HEADER_MAP.md	If sections added/changed	After doc changes
README.md	If features/setup changed	After feature work
API docs	If API changed	After API changes
Changelog	Always	After every sprint
Sprint INDEX.md	Archive completed sprint	After sprint complete

Sprint Archive Procedure

AFTER COMPLETING A SPRINT:

1. Update sprint status to COMPLETE
   - Edit sprint file header
   - Status: PENDING → COMPLETE

2. Wait archive period (default: 7 days)

3. Move to archive folder
   - mv docs/sprints/SPRINT-XXX.md docs/sprints/archive/

4. Update INDEX.md
   - Remove from Active Sprints table
   - Add to Archived Sprints reference

Documentation Review Checklist

After Code Changes

[ ] README.md
    - Installation steps still accurate?
    - Usage examples still work?
    - Configuration options current?

[ ] API Documentation
    - Endpoints current?
    - Request/response examples accurate?
    - Error codes documented?

[ ] Inline Comments
    - Complex logic explained?
    - No outdated comments?

[ ] CHANGELOG.md
    - Changes documented?
    - Version updated if needed?

After Process Changes

[ ] AGENT_GUARDRAILS.md
    - Safety protocols current?
    - New guardrails needed?

[ ] Workflow Documents
    - Procedures still accurate?
    - New workflows documented?

[ ] INDEX_MAP.md / HEADER_MAP.md
    - All documents listed?
    - Line numbers accurate?

Documentation Templates

Change Log Entry Template

## [Version] - YYYY-MM-DD

### Added
- New feature description

### Changed
- Modified behavior description

### Fixed
- Bug fix description

### Removed
- Removed feature description

### Security
- Security fix description

API Documentation Template

## Endpoint Name

**URL:** `METHOD /path/to/endpoint`

**Description:** What this endpoint does

**Headers:**
| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |

**Request Body:**
```json
{
  "field": "type - description"
}

Response:

{
  "field": "type - description"
}

Errors:

Code	Description
400	Bad request
401	Unauthorized


---

## Version Control for Docs

### Documentation Commit Patterns

COMMIT MESSAGES FOR DOCS:

docs: update README installation steps docs(api): add new endpoint documentation docs(changelog): add v1.2.0 release notes docs(guardrails): add new safety protocol


### Documentation Review Process

DOC CHANGES SHOULD BE:

Clear and accurate
Consistent with existing style
Free of typos
Properly formatted (markdown valid)
Under 500 lines (see MODULAR_DOCUMENTATION.md)


---

## Cross-Reference Maintenance

### Keeping Links Current

WHEN RENAMING/MOVING DOCS:

Search for all references to old path grep -r "old-filename.md" docs/
Update all references to new path
Update INDEX_MAP.md and HEADER_MAP.md
Verify no broken links


### Link Validation

```bash
# Find markdown links
grep -r "\[.*\](.*\.md)" docs/

# Check each link exists
# (Manual or with link checker tool)

Automated Documentation Checks

Pre-Commit Doc Checks

VERIFY BEFORE COMMITTING DOCS:

[ ] Markdown renders correctly
[ ] All links resolve
[ ] No duplicate headers
[ ] Line count under 500
[ ] No trailing whitespace

CI/CD Documentation Checks

# Example GitHub Action for doc validation
- name: Check documentation
  run: |
    # Check line counts
    find docs -name "*.md" -exec wc -l {} \; | awk '$1 > 500 {print "FAIL: " $2}'

    # Check for broken links (if tool available)
    # markdown-link-check docs/**/*.md

Update Triggers

Automatic Update Triggers

Event	Documentation Action
New file created	Add to INDEX_MAP.md
Headers changed	Update HEADER_MAP.md
API endpoint added	Update API docs
Config option added	Update README
Feature completed	Update changelog
Sprint completed	Archive sprint doc

Manual Update Schedule

REGULAR REVIEW SCHEDULE:

Weekly:
- Review active sprints for staleness
- Archive completed sprints

Monthly:
- Full documentation review
- Update "Last Updated" dates
- Check for broken links

Quarterly:
- Major documentation audit
- Update version numbers
- Review for accuracy

Quick Reference

+------------------------------------------------------------------+
|              DOCUMENTATION UPDATE QUICK REFERENCE                 |
+------------------------------------------------------------------+
| AFTER CODE CHANGES:                                               |
|   [ ] Update README if needed                                     |
|   [ ] Update API docs if endpoints changed                        |
|   [ ] Add changelog entry                                         |
+------------------------------------------------------------------+
| AFTER ADDING DOCUMENTS:                                           |
|   [ ] Add to INDEX_MAP.md                                         |
|   [ ] Add headers to HEADER_MAP.md                                |
|   [ ] Add to relevant INDEX.md                                    |
+------------------------------------------------------------------+
| AFTER SPRINT:                                                     |
|   [ ] Mark sprint COMPLETE                                        |
|   [ ] Archive after 7 days                                        |
|   [ ] Update sprint INDEX.md                                      |
+------------------------------------------------------------------+
| COMMIT PATTERN:                                                   |
|   docs(<scope>): <description>                                    |
+------------------------------------------------------------------+

Last Updated: 2026-01-14 Authored by: TheArchitectit Document Owner: Project Maintainers Line Count: ~250

6.5 KiB Raw Blame History