Skip to content

docs: Update documentation standards to 2026 best practices #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Krosebrook merged 1 commit into from
Feb 5, 2026
Merged

docs: Update documentation standards to 2026 best practices #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 19 additions & 8 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added - January 21, 2026
- **Documentation Standards Update** - Updated documentation to meet 2026 best practices
- Added status badges to README.md (build, security, documentation, vulnerabilities)
- Enhanced README.md with "Why Interact?" section and table of contents
- Improved CONTRIBUTING.md with first-time contributor guidance and communication channels
- Standardized CHANGELOG.md format for consistency
- Updated CODE_OF_CONDUCT.md with proper contact information
- Created root-level SECURITY.md for GitHub security tab integration
- Enhanced DOCUMENTATION_GUIDELINES.md with modern practices (versioning, accessibility, i18n)
- Updated all "Last Updated" dates to current date (January 21, 2026)

### Added - January 12, 2026
- **Testing Infrastructure (Feature 2)** - Implemented comprehensive testing framework
- Installed Vitest 4.0.17 + React Testing Library 16.1.0
Expand All @@ -22,22 +33,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added test scripts: `npm test`, `npm run test:ui`, `npm run test:coverage`
- Coverage baseline: 0.09% (starting point for 30% target)

### Fixed - January 12, 2026
### Fixed
- **Critical React Hooks Violations** - Fixed 4 files breaking React Hooks rules
- src/Layout.jsx - Moved useMemo before early return (line 98)
- src/components/admin/gamification/EngagementAnalytics.jsx - Moved useMemo before loading check (line 42)
- src/components/admin/gamification/SkillDevelopmentTrends.jsx - Moved useMemo before loading check (line 35)
- src/components/admin/gamification/UserProgressOverview.jsx - Moved React.useMemo before loading check (line 48)
- All hooks now called unconditionally at component top level

### Changed - January 12, 2026
### Changed
- Updated .gitignore to exclude test coverage reports
- Updated TESTING.md with implementation status and current test results
- Updated package.json with test scripts and new devDependencies

---

### Added (January 12, 2026)
### Added - January 12, 2026
- **New Documentation Files:**
- `TESTING.md`: Comprehensive testing strategy and guidelines (458 lines)
- Testing philosophy and principles
Expand Down Expand Up @@ -72,22 +83,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Version numbering guidelines
- Team roles and responsibilities

### Changed (January 12, 2026)
### Changed - January 12, 2026
- **Updated Core Documentation:**
- `README.md`: Updated with new documentation references and improved organization
- `CODEBASE_AUDIT.md`: Updated security score to 100/100 (all vulnerabilities resolved)
- `FEATURE_ROADMAP.md`: Updated Feature 1 status to reflect completed security fixes
- `DOCUMENTATION_SUMMARY.md`: Added new documentation files and updated statistics
- `CHANGELOG.md`: Updated security status to reflect zero vulnerabilities

### Fixed (January 12, 2026)
### Fixed - January 12, 2026
- Resolved 3 React Router HIGH severity XSS vulnerabilities (GHSA-2w69-qvjg-hvjx):
- Upgraded react-router-dom from 6.26.0 to 6.30.3
- Upgraded react-router from 6.30.1 to 6.30.3
- Upgraded @remix-run/router from 1.23.0 to 1.23.2
- Verified all routing and redirect functionality

### Added (January 2026)
### Added - January 2026
- **Safe Branch Merging Infrastructure:**
- `scripts/safe-merge-branch.sh`: Automated script for safely merging branches with comprehensive checks
- `scripts/cleanup-merged-branches.sh`: Utility to clean up branches that have been merged
Expand All @@ -113,7 +124,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- SECURITY_HEADERS.md: Security header configuration guide
- PRIVACY_POLICY_TEMPLATE.md: Privacy policy template for legal review

### Changed (December 2025)
### Changed - December 2025
- **BREAKING:** Replaced `react-quill` (v2.0.0) with `react-quill-new` (v3.7.0)
- Fixes Cross-Site Scripting (XSS) vulnerability in Quill editor
- Migration: Update imports from `'react-quill'` to `'react-quill-new'`
Expand All @@ -122,7 +133,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Fixes DOMPurify XSS vulnerability
- Includes updated DOMPurify v3.2.4+ with XSS protections

### Fixed (December 2025)
### Fixed - December 2025
- Resolved 8 npm security vulnerabilities (2 HIGH, 6 MODERATE severity):
- Fixed glob CLI command injection vulnerability (CVE-2025-29159) - HIGH
- Fixed js-yaml prototype pollution vulnerability - MODERATE
Expand Down
10 changes: 5 additions & 5 deletions CODE_OF_CONDUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,9 @@ This Code of Conduct applies within all community spaces, and also applies when

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at:

- **Email:** conduct@interact.app (to be established)
- **GitHub:** Use the "Report" feature on issues/PRs
- **Private:** Direct message to repository maintainers
- **Email:** conduct@krosebrook.com
- **GitHub:** Use the "Report" feature on issues/PRs, or create a private issue
- **Private:** Direct message to @Krosebrook (repository maintainer)

All complaints will be reviewed and investigated promptly and fairly.

Expand Down Expand Up @@ -125,5 +125,5 @@ If you have questions about this Code of Conduct, please reach out to the projec

---

**Document Owner:** Community Team
**Last Updated:** January 14, 2026
**Document Owner:** Community Team
**Last Updated:** January 21, 2026
34 changes: 25 additions & 9 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,15 +44,29 @@ We are committed to providing a welcoming and inspiring community for everyone.

## Getting Started

### First-Time Contributors

👋 **Welcome!** We're excited to have you contribute to Interact!

**Never contributed to open source before?** Here are some helpful resources:
- [First Contributions Guide](https://github.com/firstcontributions/first-contributions)
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
- [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/)

**Looking for a good first issue?**
- Browse issues labeled [`good first issue`](https://github.com/Krosebrook/interact/labels/good%20first%20issue)
- Check issues labeled [`help wanted`](https://github.com/Krosebrook/interact/labels/help%20wanted)
- Read through [`documentation` issues](https://github.com/Krosebrook/interact/labels/documentation) for easy entry points

### Prerequisites

Before you begin, ensure you have:

- **Node.js 18+** installed
- **Node.js 18+** installed ([Download](https://nodejs.org/))
- **npm** or **yarn** package manager
- **Git** for version control
- **Code editor** (VS Code recommended)
- **GitHub account** for pull requests
- **Git** for version control ([Download](https://git-scm.com/))
- **Code editor** (VS Code recommended, [Download](https://code.visualstudio.com/))
- **GitHub account** for pull requests ([Sign up](https://github.com/join))

### Fork and Clone

Expand Down Expand Up @@ -548,8 +562,10 @@ npm audit
### Communication Channels

- **GitHub Issues:** For bug reports and feature requests
- **Pull Requests:** For code discussions
- **GitHub Discussions:** For general questions (if enabled)
- **Pull Requests:** For code discussions and reviews
- **GitHub Discussions:** For general questions and community discussions
- **Email:** contribute@krosebrook.com (for general contribution inquiries)
- **Security:** security@krosebrook.com (for security-related issues only)
Copy link

@cubic-dev-ai cubic-dev-ai bot Feb 5, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The newly added security email conflicts with the earlier security reporting instructions that still say the contact is TBD, which can send reporters to the wrong place. Update the security reporting step to use the same email address.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At CONTRIBUTING.md, line 568:

<comment>The newly added security email conflicts with the earlier security reporting instructions that still say the contact is TBD, which can send reporters to the wrong place. Update the security reporting step to use the same email address.</comment>

<file context>
@@ -548,8 +562,10 @@ npm audit
+- **Pull Requests:** For code discussions and reviews
+- **GitHub Discussions:** For general questions and community discussions
+- **Email:** contribute@krosebrook.com (for general contribution inquiries)
+- **Security:** security@krosebrook.com (for security-related issues only)
 
 ### Common Questions
</file context>
Fix with Cubic


### Common Questions

Expand Down Expand Up @@ -628,9 +644,9 @@ Thank you for contributing to Interact! 🎉

---

**Document Owner:** Engineering Team
**Last Updated:** January 12, 2026
**Next Review:** March 2026
**Document Owner:** Engineering Team
**Last Updated:** January 21, 2026
**Next Review:** April 2026

---

Expand Down
164 changes: 156 additions & 8 deletions DOCUMENTATION_GUIDELINES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -542,18 +542,166 @@ Description...

---

## 📦 Documentation Versioning

### Version Strategy

Documentation should be versioned alongside code releases:

**Version Format:** `MAJOR.MINOR.PATCH`
- **MAJOR:** Significant documentation restructure
- **MINOR:** New sections or substantial updates
- **PATCH:** Small fixes, typos, clarifications

### Version Management

- Update version in document header when making significant changes
- Keep a changelog within each major document
- Archive old versions in `/docs/archive/vX.X/` when superseded
- Link to version history from current document

### Release Documentation

When creating a release:
1. Tag documentation version matching code version
2. Generate PDF/HTML archives for offline use
3. Update all "Version" fields in document headers
4. Create release notes summarizing documentation changes

---

## ♿ Accessibility Standards

All documentation must be accessible to users with disabilities:

### WCAG 2.1 Level AA Compliance

**Text Requirements:**
- Use semantic HTML headings (h1, h2, h3) in proper order
- Maintain 4.5:1 contrast ratio for text
- Use descriptive link text (not "click here")
- Avoid using color alone to convey information

**Images and Diagrams:**
- Provide alt text for all images
- Use descriptive captions
- Ensure diagrams have text descriptions
- Consider dark mode compatibility

**Code Examples:**
- Use syntax highlighting for readability
- Provide text alternatives for ASCII art
- Ensure examples work with screen readers

**Navigation:**
- Table of contents for documents >200 lines
- Skip navigation links for long pages
- Breadcrumb trails for nested documentation

---

## 🌍 Internationalization (i18n)

### Current Status
- English (US) is primary language
- Future: Multi-language support planned

### i18n Best Practices

**When Writing:**
- Use clear, simple English
- Avoid idioms and cultural references
- Use consistent terminology (see GLOSSARY.md)
- Keep sentences short and direct
- Use active voice

**Preparing for Translation:**
- Mark all user-facing text for translation
- Separate text from code examples
- Use ICU message format for complex strings
- Document cultural considerations
- Maintain translation glossary

**Translation Process (Future):**
1. Extract translatable strings
2. Send to translation service
3. Review translations for accuracy
4. Test with native speakers
5. Deploy translated versions

---

## 📊 Documentation Analytics

### Metrics to Track

**Usage Metrics:**
- Most viewed pages
- Average time on page
- Search queries (what users look for)
- Feedback ratings ("Was this helpful?")
- Support tickets referencing docs

**Quality Metrics:**
- Documentation coverage (% features documented)
- Freshness (last update date)
- Completeness (all sections filled)
- Accuracy (reported errors)
- Accessibility score (WCAG compliance)

### Improvement Process

1. **Analyze metrics** monthly
2. **Identify gaps** in coverage or clarity
3. **Prioritize updates** based on impact
4. **Implement changes** following guidelines
5. **Measure improvement** with follow-up metrics

---

## 🔗 Link Management

### Internal Links
- Use relative paths for repository links
- Check links before committing
- Update links when files move
- Document redirects in CHANGELOG

### External Links
- Verify links work before publishing
- Use permalinks when available
- Archive important external content
- Note when links might break (e.g., beta docs)

### Link Checking
```bash
# Install markdown-link-check
npm install -g markdown-link-check

# Check all markdown files
find . -name "*.md" -exec markdown-link-check {} \;
```

---

## 🎯 Future Improvements

Planned enhancements to documentation system:

- [ ] Automated documentation generation from code
- [ ] Interactive API documentation (Swagger/OpenAPI)
- [ ] Automated documentation generation from code (JSDoc → Markdown)
- [ ] Interactive API documentation (Swagger/OpenAPI integration)
- [ ] Video tutorials for complex features
- [ ] Documentation versioning per release
- [ ] Multi-language support
- [x] Documentation versioning per release (Added January 2026)
- [ ] Multi-language support (i18n framework ready)
- [ ] AI-powered documentation assistant
- [ ] Real-time documentation updates
- [ ] Real-time documentation search
- [ ] Community contribution portal
- [x] Accessibility standards (WCAG 2.1 AA compliance documented)
- [ ] Dark mode support for diagrams
- [ ] Documentation feedback widget
- [ ] Estimated reading time indicators
- [ ] Interactive code playgrounds
- [ ] Mobile-optimized documentation viewer

---

Expand All @@ -565,6 +713,6 @@ Planned enhancements to documentation system:

---

**Last Updated:** January 16, 2026
**Maintained by:** Krosebrook
**Version:** 1.0.0
**Last Updated:** January 21, 2026
**Maintained by:** Krosebrook
**Version:** 1.1.0
Loading
Loading