12 KiB
12 KiB
FILE PLACEMENT GUIDELINES
Comprehensive Guide for Organizing Documentation Files
DOCUMENT METADATA
Document Number: DBIS-DC-FPG-001
Version: 1.0
Date: 2024-12-08
Classification: UNCLASSIFIED
Authority: DBIS Executive Directorate
Approved By: [See signature block - requires SCC approval]
Effective Date: 2024-12-08
Distribution: Distribution Statement A - Public Release Unlimited
Change Log:
- 2024-12-08 - Version 1.0 - Initial Release
EXECUTIVE SUMMARY
This document provides comprehensive guidelines for file placement within the DBIS documentation corpus. It establishes clear rules for where new files should be placed and how existing files should be organized to maintain the clean, logical structure established in December 2024.
Purpose: Ensure consistent file organization and prevent root directory clutter.
ROOT DIRECTORY GUIDELINES
Files That Belong in Root
Only essential navigation and reference files should remain in the project root:
- README.md - Main project documentation and entry point
- GLOSSARY.md - Terms and definitions (referenced in README)
- MASTER_INDEX.md - Complete document inventory (referenced in README)
- NAVIGATION_GUIDE.md - Navigation assistance (referenced in README)
- QUICK_REFERENCE.md - Fast navigation guide (referenced in README)
- DOCUMENT_RELATIONSHIP_MAP.md - Document relationships (referenced in README)
- EXECUTIVE_SUMMARY.md - High-level overview (referenced in README)
- REMAINING_PHASES_SUMMARY.md - Remaining phases list (referenced in README)
- RESOURCE_REQUIREMENTS_SUMMARY.md - Resource planning (referenced in README)
- RECOMMENDATIONS_AND_SUGGESTIONS.md - Recommendations (referenced in README)
- QUALITY_VERIFICATION_REPORT.md - Quality metrics (referenced in README)
- TIMELINE_VISUALIZATION.md - Project timeline (referenced in README)
- VERSION_CONTROL_POLICY.md - Version control standards
- DOCUMENTATION_STANDARDS.md - Documentation standards
- IMMEDIATE_ACTIONABLE_TASKS.md - Current actionable tasks
Rule: If a file is not directly referenced in README.md as a primary navigation tool, it should NOT be in the root directory.
PROJECT_MANAGEMENT/ DIRECTORY STRUCTURE
Root Directory (project_management/)
Should Contain:
- ✅ README.md - Directory index (required)
- ✅ IMMEDIATE_NEXT_STEPS.md - Active planning document (truly active, not historical)
Should NOT Contain:
- ❌ Completion reports
- ❌ Status reports
- ❌ Execution summaries
- ❌ Historical phase documents
- ❌ Implementation tracking documents
project_management/reports/ Subdirectory
Should Contain:
- ✅ All completion reports (ALL_, COMPLETE_, COMPLETION_, FINAL_)
- ✅ All status reports (PROJECT_STATUS, IMPLEMENTATION_STATUS, etc.)
- ✅ All execution summaries (NEXT_STEPS_EXECUTION_SUMMARY, REMAINING_*_EXECUTION_SUMMARY)
- ✅ All verification reports (CROSS_REFERENCE_VERIFICATION, GRADING_AND_SCORING)
- ✅ All organization reports (ORGANIZATION_*, PROJECT_ROOT_REVIEW)
- ✅ All phase completion summaries (PHASE_*_COMPLETION_SUMMARY)
File Naming Patterns:
*_COMPLETE*.md*_COMPLETION*.md*_STATUS*.md*_REPORT*.md*_SUMMARY*.md(execution summaries)*_VERIFICATION*.md
project_management/phases/ Subdirectory
Should Contain:
- ✅ All phase-specific documentation (PHASE_1_, PHASE_2_, etc.)
- ✅ Phase planning documents (PHASE_*_PLANNING.md)
- ✅ Phase quick start guides (PHASE_*_QUICK_START.md)
- ✅ Phase progress reports (PHASE_*_PROGRESS_REPORT.md)
- ✅ Phase content completion documents (PHASE_*_CONTENT_COMPLETE.md)
- ✅ Phase final summaries (PHASE_*_FINAL_SUMMARY.md)
- ✅ Phase execution documents (PHASE_EXECUTION_STARTED.md)
File Naming Patterns:
PHASE_*.md
project_management/implementation/ Subdirectory
Should Contain:
- ✅ Implementation tracking documents (IMPLEMENTATION_STATUS.md)
- ✅ Implementation task lists (IMPLEMENTATION_TASK_LIST.md)
- ✅ Implementation readiness reports (IMPLEMENTATION_READINESS_REPORT.md)
File Naming Patterns:
IMPLEMENTATION_*.md
00_DOCUMENT_CONTROL/ DIRECTORY STRUCTURE
Root Directory (00_document_control/)
Should Contain:
- ✅ README.md - Directory index (required)
- ✅ Framework/overview documents (Future_Enhancements_Roadmap.md)
- ✅ High-level planning documents
Should NOT Contain:
- ❌ Specific process documents
- ❌ Specific standards documents
- ❌ Specific system documents
- ❌ Specific phase specifications
00_document_control/standards/ Subdirectory
Should Contain:
- ✅ Compliance documentation (DoD_MilSpec_Compliance_Summary.md)
- ✅ Standards specifications (Document_Control_Standards.md)
- ✅ Regulatory frameworks (NIST_800-53_, ISO_9001_)
- ✅ Enhanced standards (Enhanced_NIST_800-53_Controls.md)
File Naming Patterns:
*_Standards.md*_Compliance*.md*_NIST*.md*_ISO*.md*_DoD*.md*_MilSpec*.md
00_document_control/processes/ Subdirectory
Should Contain:
- ✅ Process documentation (Change_Management_Process.md)
- ✅ Procedures and workflows (Change_Notification_Procedures.md)
- ✅ Management frameworks (Risk_Management_Framework.md)
- ✅ Quality processes (Quality_Assurance_Plan.md)
- ✅ Configuration processes (Configuration_Management_Plan.md)
- ✅ Security processes (Security_Classification_Guide.md)
- ✅ Maintenance processes (Maintenance_Schedule.md)
- ✅ Update processes (Update_Trigger_Procedures.md)
- ✅ Versioning processes (Versioning_Enhancement_Specification.md)
- ✅ CCB documents (CCB_Charter.md)
- ✅ Checklists (Resource_Allocation_Checklist.md)
- ✅ Frameworks (Template_System_Framework.md)
File Naming Patterns:
*_Process.md*_Procedures.md*_Plan.md(process plans)*_Framework.md*_Guide.md(process guides)*_Charter.md*_Checklist.md*_Schedule.md
00_document_control/phases/ Subdirectory
Should Contain:
- ✅ Phase-specific specifications (Phase_4_Usability_Specifications.md)
- ✅ Phase requirements (Phase_5_Training_Framework.md)
- ✅ Phase execution checklists (Phase_Execution_Checklists.md)
- ✅ Training programs (Training_Program_Outline.md)
File Naming Patterns:
Phase_*.md*_Training*.md(phase-related training)
00_document_control/systems/ Subdirectory
Should Contain:
- ✅ System implementation guides (System_Implementation_Guide.md)
- ✅ System specifications (Template_System_Requirements.md)
- ✅ Technical frameworks (User_Support_System_Framework.md)
- ✅ Resource planning (Resource_Allocation_Plan.md)
- ✅ Project execution plans (Project_Execution_Plan.md)
- ✅ Development assessments (Development_Readiness_Assessment.md)
- ✅ Visual content packages (Visual_Content_Work_Packages.md)
- ✅ Format specifications (Mobile_Format_Specification.md)
File Naming Patterns:
*_Implementation*.md*_System*.md*_Plan.md(system/implementation plans)*_Guide.md(system guides)*_Assessment.md*_Specification.md(system specifications)*_Work_Packages.md
DECISION TREE FOR FILE PLACEMENT
Step 1: Is it a navigation/reference file referenced in README.md?
- YES → Place in root directory
- NO → Continue to Step 2
Step 2: Is it a project management document?
- YES → Continue to Step 3
- NO → Continue to Step 6
Step 3: Is it a completion/status/execution report?
- YES → Place in project_management/reports/
- NO → Continue to Step 4
Step 4: Is it phase-specific documentation?
- YES → Place in project_management/phases/
- NO → Continue to Step 5
Step 5: Is it implementation tracking?
- YES → Place in project_management/implementation/
- NO → Place in project_management/reports/ (default for PM docs)
Step 6: Is it a document control document?
- YES → Continue to Step 7
- NO → Place in appropriate category directory (01_constitutional/, 02_statutory_code/, etc.)
Step 7: Is it a standard/compliance document?
- YES → Place in 00_document_control/standards/
- NO → Continue to Step 8
Step 8: Is it a process/procedure document?
- YES → Place in 00_document_control/processes/
- NO → Continue to Step 9
Step 9: Is it a phase specification?
- YES → Place in 00_document_control/phases/
- NO → Continue to Step 10
Step 10: Is it a system/implementation document?
- YES → Place in 00_document_control/systems/
- NO → Place in 00_document_control/ root (framework documents only)
EXAMPLES
Example 1: New Completion Report
File: PHASE_3_COMPLETION_SUMMARY.md
Decision: Completion report → project_management/reports/PHASE_3_COMPLETION_SUMMARY.md
Example 2: New Process Document
File: Incident_Response_Procedures.md
Decision: Process document → 00_document_control/processes/Incident_Response_Procedures.md
Example 3: New Standard Document
File: ISO_27001_Compliance_Framework.md
Decision: Standards document → 00_document_control/standards/ISO_27001_Compliance_Framework.md
Example 4: New Phase Document
File: PHASE_3_PLANNING.md
Decision: Phase document → project_management/phases/PHASE_3_PLANNING.md
Example 5: New System Guide
File: Deployment_System_Guide.md
Decision: System document → 00_document_control/systems/Deployment_System_Guide.md
MAINTENANCE PROCEDURES
When Adding New Files
- Review file name and content to determine category
- Use decision tree to identify correct location
- Check existing files in target directory for naming consistency
- Place file in correct subdirectory
- Update README.md in target directory if needed
- Update cross-references in related documents
- Run link verification after placement
When Moving Existing Files
- Identify correct target location using decision tree
- Move file to target location
- Update all references to the file:
- Search for references:
grep -r "filename.md" . - Update relative paths in all referencing files
- Search for references:
- Update README files in source and target directories
- Run link verification to ensure all links work
- Document move in change log
When in Doubt
- Check existing similar files to see where they are placed
- Review PROJECT_ORGANIZATION_REVIEW.md for categorization examples
- Consult this guide for decision tree
- Default rule: When uncertain, place in most specific subdirectory (not root)
ENFORCEMENT
Pre-Commit Checks
Before committing new files:
- Verify file is in correct location
- Verify file naming follows conventions
- Verify README files are updated
- Run link verification script
Periodic Reviews
- Monthly: Review root directory for misplaced files
- Quarterly: Review subdirectories for proper organization
- After major changes: Full structure review
RELATED DOCUMENTS
- PROJECT_ORGANIZATION_REVIEW.md - Complete reorganization analysis
- project_management/README.md - Project management structure
- 00_document_control/README.md - Document control structure
- Document Control Standards - Document control standards
- Configuration Management Plan - Configuration management
END OF FILE PLACEMENT GUIDELINES