9c37af10c0
- Fixed 104 broken references in 59 files - Consolidated 40+ duplicate status files - Archived duplicates to reports/archive/duplicates/ - Created scripts for reference fixing and consolidation - Updated content inconsistency reports All optional cleanup tasks complete.
191 lines
3.6 KiB
Markdown
191 lines
3.6 KiB
Markdown
# Contributor Guidelines
|
|
|
|
**Last Updated:** 2025-01-20
|
|
**Document Version:** 1.0
|
|
**Status:** Active Documentation
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This document provides guidelines for contributing to the documentation, including style standards, review process, and approval workflow.
|
|
|
|
---
|
|
|
|
## Style Guide Reference
|
|
|
|
**Primary Reference:**
|
|
- [DOCUMENTATION_STYLE_GUIDE.md](DOCUMENTATION_STYLE_GUIDE.md) ⭐⭐⭐
|
|
|
|
**Key Standards:**
|
|
- File naming: `UPPERCASE_WITH_UNDERSCORES.md`
|
|
- Headers: Include Last Updated, Document Version, Status
|
|
- Cross-references: Use Related Documentation sections
|
|
- Code blocks: Include language identifiers and expected output
|
|
|
|
---
|
|
|
|
## Contribution Process
|
|
|
|
### Step 1: Identify Need
|
|
|
|
**Ways to contribute:**
|
|
- Fix errors or outdated information
|
|
- Add missing documentation
|
|
- Improve existing documentation
|
|
- Add examples or use cases
|
|
- Create diagrams or visualizations
|
|
|
|
---
|
|
|
|
### Step 2: Follow Standards
|
|
|
|
**Before contributing:**
|
|
1. Read [DOCUMENTATION_STYLE_GUIDE.md](DOCUMENTATION_STYLE_GUIDE.md)
|
|
2. Review similar documents for consistency
|
|
3. Use templates where available
|
|
4. Follow naming conventions
|
|
|
|
---
|
|
|
|
### Step 3: Create/Update Document
|
|
|
|
**For new documents:**
|
|
- Use appropriate directory structure
|
|
- Follow style guide header format
|
|
- Include Related Documentation section
|
|
- Add to MASTER_INDEX.md
|
|
|
|
**For updates:**
|
|
- Update Last Updated date
|
|
- Increment Document Version if significant changes
|
|
- Update change log if document has one
|
|
- Verify all links still work
|
|
|
|
---
|
|
|
|
### Step 4: Review and Test
|
|
|
|
**Self-review checklist:**
|
|
- [ ] Follows style guide
|
|
- [ ] All links work
|
|
- [ ] Code examples tested (if applicable)
|
|
- [ ] No placeholder content
|
|
- [ ] Proper cross-references
|
|
- [ ] Added to index files
|
|
|
|
---
|
|
|
|
### Step 5: Submit for Review
|
|
|
|
**Review process:**
|
|
1. Create pull request or notify team
|
|
2. Include description of changes
|
|
3. Reference related issues/tasks
|
|
4. Wait for review approval
|
|
|
|
---
|
|
|
|
## Approval Workflow
|
|
|
|
### Review Levels
|
|
|
|
**Level 1: Self-Review**
|
|
- Minor corrections
|
|
- Formatting fixes
|
|
- Link updates
|
|
|
|
**Level 2: Peer Review**
|
|
- New documents
|
|
- Significant updates
|
|
- Configuration changes
|
|
|
|
**Level 3: Team Review**
|
|
- Architecture changes
|
|
- Major procedure changes
|
|
- Policy updates
|
|
|
|
---
|
|
|
|
## Examples and Templates
|
|
|
|
### New Document Template
|
|
|
|
```markdown
|
|
# Document Title
|
|
|
|
**Navigation:** [Home](01-getting-started/README.md) > [Category](01-getting-started/README.md) > Document Title
|
|
|
|
**Last Updated:** YYYY-MM-DD
|
|
**Document Version:** 1.0
|
|
**Status:** 🟢 Active Documentation
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
[Document purpose and scope]
|
|
|
|
---
|
|
|
|
[Content sections]
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- **[Related Doc 1](path/to/doc1.md)** ⭐⭐⭐ - Description
|
|
- **[Related Doc 2](path/to/doc2.md)** ⭐⭐ - Description
|
|
|
|
---
|
|
|
|
**Last Updated:** YYYY-MM-DD
|
|
**Review Cycle:** [Monthly/Quarterly/As Needed]
|
|
```
|
|
|
|
---
|
|
|
|
## Common Contribution Types
|
|
|
|
### Adding Examples
|
|
|
|
**Guidelines:**
|
|
- Use real-world scenarios
|
|
- Include expected outputs
|
|
- Test examples before documenting
|
|
- Update if procedures change
|
|
|
|
---
|
|
|
|
### Fixing Errors
|
|
|
|
**Process:**
|
|
1. Identify error
|
|
2. Verify correct information
|
|
3. Update document
|
|
4. Update related documents if needed
|
|
5. Test fix
|
|
|
|
---
|
|
|
|
### Adding Diagrams
|
|
|
|
**Guidelines:**
|
|
- Use Mermaid for new diagrams
|
|
- Follow diagram standards
|
|
- Reference in text
|
|
- Update visual index
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- **[DOCUMENTATION_STYLE_GUIDE.md](DOCUMENTATION_STYLE_GUIDE.md)** ⭐⭐⭐ - Style guide
|
|
- **[MASTER_INDEX.md](MASTER_INDEX.md)** ⭐⭐⭐ - Documentation index
|
|
- **[MAINTENANCE_REVIEW_SCHEDULE.md](MAINTENANCE_REVIEW_SCHEDULE.md)** ⭐ - Review schedule
|
|
|
|
---
|
|
|
|
**Last Updated:** 2025-01-20
|
|
**Review Cycle:** Quarterly
|