# Documentation Structure Guide **Last Updated:** 2026-01-07 Complete guide to the tools-pages documentation structure, file organization, and when to create vs update files. ## Directory Structure ``` docs/guides/tools-pages/ ├── README.md # Main index and quick reference ├── TOOL_DOCUMENTATION_TEMPLATE.md # Standardized template ├── TOOLS_INVENTORY.md # Complete tool list ├── TOOLS_MAINTENANCE_GUIDE.md # Annual update process ├── DOCUMENTATION_MAINTENANCE_PROCESS.md # Documentation maintenance ├── DOCUMENTATION_STRUCTURE.md # This file ├── DOCUMENTATION_REORGANIZATION_LOG.md # Reorganization tracking │ ├── [Tool]-documentation.md # 17 tool-specific docs │ ├── FINAL_STATUS_2026.md # Consolidated project status ├── TESTING_SUMMARY_2026.md # Consolidated testing status ├── VERIFICATION_SUMMARY_2026.md # Consolidated verification ├── NEXT_STEPS_2026.md # Consolidated next steps │ ├── [Detailed Reference Files] # Keep for detail │ ├── COMPLETE_VERIFICATION_SUMMARY_2026.md │ ├── COMPREHENSIVE_TESTING_SUMMARY_2026.md │ ├── VALUE_VERIFICATION_RESULTS_2026.md │ ├── CODE_ANALYSIS_RESULTS.md │ ├── TOOL_BY_TOOL_ANALYSIS.md │ └── ... │ └── [Framework Files] # Testing/analysis frameworks ├── BROWSER_TESTING_FRAMEWORK.md ├── CODE_ANALYSIS_FRAMEWORK.md └── ... ``` ## File Types ### Core Documentation (Always Keep) **Tool Documentation (17 files):** - `*-documentation.md` - One file per tool - Comprehensive documentation following template - Updated when code/content changes - Updated annually for year references **Core Reference Files:** - `README.md` - Main index - `TOOL_DOCUMENTATION_TEMPLATE.md` - Documentation template - `TOOLS_INVENTORY.md` - Tool list - `TOOLS_MAINTENANCE_GUIDE.md` - Maintenance process - `DOCUMENTATION_MAINTENANCE_PROCESS.md` - Doc maintenance - `DOCUMENTATION_STRUCTURE.md` - Structure guide ### Consolidated Status Files (Update, Don't Create New) **Master Status Files:** - `FINAL_STATUS_2026.md` - Overall project status - `TESTING_SUMMARY_2026.md` - Testing status and plans - `VERIFICATION_SUMMARY_2026.md` - Verification results - `NEXT_STEPS_2026.md` - Next steps and action items **How to Use:** - Update existing files when status changes - Don't create new status files - Reference detailed files for specifics ### Detailed Reference Files (Keep for Detail) **Analysis & Research:** - `COMPLETE_VERIFICATION_SUMMARY_2026.md` - Detailed verification - `COMPREHENSIVE_TESTING_SUMMARY_2026.md` - Detailed testing - `VALUE_VERIFICATION_RESULTS_2026.md` - Verification results - `CODE_ANALYSIS_RESULTS.md` - Code analysis - `TOOL_BY_TOOL_ANALYSIS.md` - Tool analysis - `FINAL_2026_RESEARCH_REPORT.md` - Research report - `COMPREHENSIVE_UPDATE_PLAN_2026.md` - Update plan - `BROWSER_TESTING_PLAN_2026.md` - Testing plan - `SCHEMA_VALIDATION_PLAN_2026.md` - Schema plan **Purpose:** - Provide detailed information - Reference from consolidated files - Keep for historical reference ### Framework Files (Keep) **Testing & Analysis:** - `BROWSER_TESTING_FRAMEWORK.md` - Testing framework - `CODE_ANALYSIS_FRAMEWORK.md` - Code analysis framework - `TESTING_CHECKLIST_2026.md` - Testing checklist **Purpose:** - Standardized processes - Reusable templates - Best practices ### Research & Analysis Files (Keep) **Research:** - `2026_LAW_CHANGES_RESEARCH.md` - Law changes research - `FUTURE_UPDATES_2026.md` - Monitoring schedule - `IMMEDIATE_UPDATES_CHECKLIST_2026.md` - Update checklist - `CONTENT_ANALYSIS_SUMMARY_2026.md` - Content analysis - `CONTENT_UPDATE_CHECKLIST_2026.md` - Content checklist - `FAQ_UPDATE_CHECKLIST_2026.md` - FAQ checklist **Purpose:** - Research findings - Update checklists - Monitoring schedules ### QA Files (Keep) **QA Reports:** - `QA_COMPLETENESS_REPORT.md` - Completeness check - `QA_CONSISTENCY_REPORT.md` - Consistency check - `QA_ACCURACY_REPORT.md` - Accuracy check - `QA_BROWSER_TESTING_SUMMARY.md` - Browser testing - `QA_CODE_ANALYSIS_SUMMARY.md` - Code analysis **Purpose:** - Quality assurance - Verification reports - Best practices ## What Goes in Each File Type ### Tool Documentation (`*-documentation.md`) **Contains:** - Tool overview (purpose, use cases, audience) - Technical documentation (files, modes, constants) - Calculation logic (formulas, examples) - Content documentation (hero, FAQs, meta tags) - 2026 Update Requirements (what needs updating) - Change log (track all updates) - Annual update checklist (embedded) - Version history (major changes) - Maintenance notes (ongoing requirements) **When to Update:** - When code changes - During annual updates - When content changes - When new features added ### Consolidated Status Files **FINAL_STATUS_2026.md:** - Overall project status - Phase completions - Values summary - Quality metrics - References to detailed files **TESTING_SUMMARY_2026.md:** - Testing status - Code verification results - Browser testing plans - Schema validation plans - References to detailed plans **VERIFICATION_SUMMARY_2026.md:** - Verification results - Updated values - Confirmed values - Verification sources - Files modified **NEXT_STEPS_2026.md:** - Current status - Next steps - Priorities - Action items - References to detailed plans **When to Update:** - When status changes - When phases complete - When new information available - Don't create new files (update existing) ### Detailed Reference Files **Contains:** - Detailed analysis - Specific findings - Exact locations - Comprehensive information **Purpose:** - Provide detail - Reference from consolidated files - Historical reference **When to Update:** - When new information available - When analysis complete - Keep for reference ## When to Create New Files vs Update Existing ### ✅ Update Existing Files **Tool Documentation:** - Always update existing `*-documentation.md` file - Never create duplicate tool docs **Consolidated Status Files:** - Always update existing consolidated files - Never create new status files **Core Reference Files:** - Update README.md when structure changes - Update maintenance guide when process changes - Update template when structure changes ### ✅ Create New Files (Rare) **Only Create New Files For:** - New tools (new `*-documentation.md`) - New frameworks (if truly new approach) - New analysis (if unique, not duplicating existing) **Don't Create New Files For:** - Status updates (update consolidated files) - Progress tracking (update consolidated files) - New findings (add to existing analysis files) ## File Naming Conventions ### Tool Documentation **Pattern:** `[tool-name]-documentation.md` **Examples:** - `minijob-rechner-documentation.md` - `midijob-rechner-documentation.md` - `arbeitslosengeld-rechner-documentation.md` ### Consolidated Status Files **Pattern:** `[CATEGORY]_SUMMARY_2026.md` or `[CATEGORY]_STATUS_2026.md` **Examples:** - `FINAL_STATUS_2026.md` - `TESTING_SUMMARY_2026.md` - `VERIFICATION_SUMMARY_2026.md` - `NEXT_STEPS_2026.md` ### Detailed Reference Files **Pattern:** `[DESCRIPTIVE_NAME]_2026.md` or `[DESCRIPTIVE_NAME].md` **Examples:** - `COMPLETE_VERIFICATION_SUMMARY_2026.md` - `COMPREHENSIVE_TESTING_SUMMARY_2026.md` - `VALUE_VERIFICATION_RESULTS_2026.md` ### Framework Files **Pattern:** `[CATEGORY]_FRAMEWORK.md` or `[CATEGORY]_GUIDE.md` **Examples:** - `BROWSER_TESTING_FRAMEWORK.md` - `CODE_ANALYSIS_FRAMEWORK.md` ## Directory Organization ### Current Structure **Flat Structure:** - All files in `docs/guides/tools-pages/` - Easy to find and reference - Clear naming conventions **Benefits:** - Simple navigation - Easy to search - Clear file purposes ### File Organization Principles 1. **Consolidate, Don't Duplicate** - Use consolidated status files - Don't create duplicate files 2. **Update, Don't Create** - Update existing files - Don't create new status files 3. **Reference, Don't Repeat** - Reference detailed files - Don't duplicate information 4. **Clear Naming** - Use descriptive names - Follow naming conventions - Make purpose clear ## Maintenance Guidelines ### Regular Maintenance **Quarterly:** - Review official sources - Update affected tool docs - Update consolidated status files **Annually:** - Comprehensive update of all tool docs - Review documentation structure - Clean up outdated files ### When Making Changes 1. **Read First** - Read existing documentation - Understand current structure - Identify what needs updating 2. **Update Existing** - Update existing files - Don't create duplicates - Use consolidated files 3. **Document Changes** - Update "Last Updated" date - Add change log entry - Update consolidated status files 4. **Verify** - Check all references updated - Check no duplicates created - Check structure maintained ## References - **Documentation Maintenance Process:** `DOCUMENTATION_MAINTENANCE_PROCESS.md` - **Tool Documentation Template:** `TOOL_DOCUMENTATION_TEMPLATE.md` - **Maintenance Guide:** `TOOLS_MAINTENANCE_GUIDE.md` - **README:** `README.md` --- **Note:** This structure ensures documentation is organized, maintainable, and efficient for both human maintainers and AI agents.