337 lines
12 KiB
Markdown
337 lines
12 KiB
Markdown
|
# 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:**
|
||
|
|
|
||
|
|
1. **README.md** - Main project documentation and entry point
|
||
|
|
2. **GLOSSARY.md** - Terms and definitions (referenced in README)
|
||
|
|
3. **MASTER_INDEX.md** - Complete document inventory (referenced in README)
|
||
|
|
4. **NAVIGATION_GUIDE.md** - Navigation assistance (referenced in README)
|
||
|
|
5. **QUICK_REFERENCE.md** - Fast navigation guide (referenced in README)
|
||
|
|
6. **DOCUMENT_RELATIONSHIP_MAP.md** - Document relationships (referenced in README)
|
||
|
|
7. **EXECUTIVE_SUMMARY.md** - High-level overview (referenced in README)
|
||
|
|
8. **REMAINING_PHASES_SUMMARY.md** - Remaining phases list (referenced in README)
|
||
|
|
9. **RESOURCE_REQUIREMENTS_SUMMARY.md** - Resource planning (referenced in README)
|
||
|
|
10. **RECOMMENDATIONS_AND_SUGGESTIONS.md** - Recommendations (referenced in README)
|
||
|
|
11. **QUALITY_VERIFICATION_REPORT.md** - Quality metrics (referenced in README)
|
||
|
|
12. **TIMELINE_VISUALIZATION.md** - Project timeline (referenced in README)
|
||
|
|
13. **VERSION_CONTROL_POLICY.md** - Version control standards
|
||
|
|
14. **DOCUMENTATION_STANDARDS.md** - Documentation standards
|
||
|
|
15. **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
|
||
|
|
|
||
|
|
1. **Review file name and content** to determine category
|
||
|
|
2. **Use decision tree** to identify correct location
|
||
|
|
3. **Check existing files** in target directory for naming consistency
|
||
|
|
4. **Place file** in correct subdirectory
|
||
|
|
5. **Update README.md** in target directory if needed
|
||
|
|
6. **Update cross-references** in related documents
|
||
|
|
7. **Run link verification** after placement
|
||
|
|
|
||
|
|
### When Moving Existing Files
|
||
|
|
|
||
|
|
1. **Identify correct target location** using decision tree
|
||
|
|
2. **Move file** to target location
|
||
|
|
3. **Update all references** to the file:
|
||
|
|
- Search for references: `grep -r "filename.md" .`
|
||
|
|
- Update relative paths in all referencing files
|
||
|
|
4. **Update README files** in source and target directories
|
||
|
|
5. **Run link verification** to ensure all links work
|
||
|
|
6. **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:
|
||
|
|
1. Verify file is in correct location
|
||
|
|
2. Verify file naming follows conventions
|
||
|
|
3. Verify README files are updated
|
||
|
|
4. 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](../../PROJECT_ORGANIZATION_REVIEW.md) - Complete reorganization analysis
|
||
|
|
- [project_management/README.md](../../project_management/README.md) - Project management structure
|
||
|
|
- [00_document_control/README.md](../README.md) - Document control structure
|
||
|
|
- [Document Control Standards](standards/Document_Control_Standards.md) - Document control standards
|
||
|
|
- [Configuration Management Plan](Configuration_Management_Plan.md) - Configuration management
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
**END OF FILE PLACEMENT GUIDELINES**
|
||
|
|
|