[Research]: Consolidate project documentation and ADRs #1957
Conversation
- DOCUMENTATION_CONSOLIDATION_PLAN.md: Detailed 4-phase plan for improving docs - DOCUMENTATION_CONSOLIDATION_REVIEW.md: Expert review feedback from 3 specialized agents Analysis Summary: - Current docs are 8.5/10 health score (already good) - Identified gaps: quick reference, module discoverability, metadata inconsistency - Original plan: 36-44 hours (realistic: 80-120 hours) - Recommended lean plan: 22-27 hours with 80% value retention Key Recommendations: - Create Quick Reference Guide (highest value, unanimous agreement) - Create Module Index and ADR Index - Add minimal metadata (4-6 fields, not 12) - Skip feature hubs (too complex) and documentation map (redundant) - Implement Week 1-2 only, then evaluate Reviews conducted by: 1. Documentation Architecture Specialist (6.5/10 - over-engineered) 2. LLM Context Optimization Specialist (7.2/10 - solid, missing semantic metadata) 3. Developer Experience Specialist (5.5/10 - most features will be ignored) All reviewers recommend simplified "Lean Plan" approach for better ROI.
…cs-adrs-011CV3QpHV7XeRGaAtJkuK2r
- Created: docs-site/docs/development/research/documentation-improvement-recommendations.md - Removed: DOCUMENTATION_CONSOLIDATION_PLAN.md (merged) - Removed: DOCUMENTATION_CONSOLIDATION_REVIEW.md (merged) This consolidates all documentation research and expert reviews into one comprehensive, actionable guide optimized for both LLM and human use. Key Recommendations: - Week 1 (14-17 hours): Quick Reference, Module Index, ADR Index, Fix CLAUDE.md - Week 2 (8-10 hours, optional): Documentation standards, minimal metadata - Week 3+ (optional): LLM enhancements, feature pages Expert Reviews Summary: - Architecture Specialist: 6.5/10 (over-engineered) - LLM Optimization: 7.2/10 (solid foundation, missing semantic metadata) - Developer Experience: 5.5/10 (most features will be ignored) Consensus: Focus on high-value, low-maintenance deliverables. Target: 80% value with 60% less effort (22-27 hours vs 80-120 hours). Next Steps: 1. Review consolidated recommendations 2. Decide on Week 1 vs Week 1-2 implementation 3. Start with Quick Reference Guide (highest value) 4. Measure engagement before proceeding further
…cs-adrs-011CV3QpHV7XeRGaAtJkuK2r
Recent changes from main that affect the plan: - CLAUDE.md already updated with local documentation references - ADR-004 created (agents.md standard investigation - rejected) - New startup module added (app/startup/) - Instruction files consolidated (28% duplication removed) - Markdown standards centralized in contributing.md Plan updates: - Reduced Week 1 effort from 14-17 hours to 12-15 hours - Updated module count: 21 → 22 modules (added startup) - Updated ADR count: 3 → 4 ADRs (added ADR-004) - Marked CLAUDE.md task as 90% complete (only minor enhancements needed) - Added "Recent improvements" section to Executive Summary - Updated all effort estimates throughout document - Added ADR-004 to ADR Index examples - Added startup module to Module Index examples Key insight: Recent consolidation work in main branch already addressed some planned improvements, demonstrating the project is actively maintaining documentation quality.
Summary of ChangesHello @IsmaelMartinez, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a detailed research document outlining a strategic approach to enhance the project's documentation. It proposes a pragmatic, phased plan to improve both human usability and LLM consumption of the documentation, focusing on high-impact changes like quick reference guides and structured indexes, while deliberately avoiding over-engineered solutions that could lead to high maintenance burdens. The goal is to achieve significant improvements in developer experience and LLM optimization with a sustainable, low-effort investment. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
This research document was missing from the index. Added it to the Strategic Analysis section with a brief description highlighting: - Expert review basis (3 perspectives) - Week 1 deliverables (Quick Reference, Module Index, ADR Index) - Value proposition (80% value, 60% less effort)
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds a comprehensive research document outlining recommendations for improving the project's documentation. The document is well-structured and provides a clear, actionable plan. My review focuses on ensuring the correctness of links within this new document and the proposed content. I've identified a few broken relative links that need correction to ensure proper navigation.
docs-site/docs/development/research/documentation-improvement-recommendations.md
Outdated
Show resolved
Hide resolved
docs-site/docs/development/research/documentation-improvement-recommendations.md
Outdated
Show resolved
Hide resolved
docs-site/docs/development/research/documentation-improvement-recommendations.md
Outdated
Show resolved
Hide resolved
📦 PR Build Artifacts✅ Build successful! Download artifacts:
|
…recommendations.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
IsmaelMartinez
changed the title
From docs-site/docs/development/module-index.md, the correct path to repository root is ../../../, not ../../ Changed all module README paths from: ../../app/*/README.md (incorrect - resolves to docs-site/app/*) To: ../../../app/*/README.md (correct - resolves to repo root app/*)
From docs-site/docs/development/research/*.md, the correct path to repository root is ../../../../, not ../../../ Changed CLAUDE.md path from: ../../../CLAUDE.md (incorrect - resolves to docs-site/CLAUDE.md) To: ../../../../CLAUDE.md (correct - resolves to repo root CLAUDE.md) Fixed in both YAML frontmatter and Related Documentation section.
Docusaurus cannot resolve markdown links outside the docs directory. Changed from markdown link to plain text reference. The YAML frontmatter reference is preserved (Docusaurus doesn't validate those), but the markdown link in the content now uses plain text instead of a link that would break the build. Fixes: MDX compilation error for ../../../../CLAUDE.md
Docusaurus doesn't support directory links - they must point to files. Changed: - ../adr/ → ../adr/002-token-cache-secure-storage.md (example ADR) - . → README.md (current directory index) This fixes the broken link error: -> linking to ../adr/ (resolved as: /development/adr/)
- Deleted token-cache-authentication-research.md (superseded by ADR-002, ADR-003) - Deleted secure-storage-research.md (superseded by ADR-002) - Deleted documentation-health-analysis.md (consolidated into documentation-improvement-recommendations.md) - Updated research/README.md to remove references and point to relevant ADRs - Git history preserves all deleted content for reference
- Changed all module README links from relative paths to GitHub URLs - Docusaurus cannot link to files outside docs/ directory - GitHub links provide direct access to source documentation
IsmaelMartinez
added
ready
- Removed token-cache-authentication-research (superseded by ADR-002, ADR-003) - Removed secure-storage-research (superseded by ADR-002) - Removed documentation-health-analysis (consolidated into documentation-improvement-recommendations) - Added documentation-improvement-recommendations to Strategic Analysis section - Added ADR-004 (agents.md standard investigation) to Architecture Decisions section
- Updated development/README.md to reference ADR-002 and ADR-003 instead of deleted research files - Updated architecture-modernization-research.md references to point to ADRs - Updated ui-system-strategic-analysis.md to reference documentation-improvement-recommendations.md instead of deleted documentation-health-analysis.md All links now point to existing files in the documentation.
- Changed from non-existent --partition flag to correct --class and --user-data-dir flags - Added profile comments for clarity - Commands now match the actual multiple-instances.md documentation
|
This pull request introduces a detailed research document outlining a strategic approach to enhance the project's documentation. It proposes a pragmatic, phased plan to improve both human usability and LLM consumption of the documentation, focusing on high-impact changes like quick reference guides and structured indexes, while deliberately avoiding over-engineered solutions that could lead to high maintenance burdens. The goal is to achieve significant improvements in developer experience and LLM optimization with a sustainable, low-effort investment.