docs: Update and organize documentation #48
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Update PROBLEM_CATALOG.md with correct problem count (36 total) - Fixed Expert level count from 8 to 9 - Added missing SYS-001 problem entry - Updated Intermediate count from 8 to 9 - Update SYSTEM_OVERVIEW.md with current information - Changed "15+ problems" to actual count of 36 - Fixed difficulty level for CLI-001 (Basic not Beginner) - Fixed difficulty level for NET-001 (Intermediate not Advanced) - Reorganized problem tables to show all Advanced and Expert problems - Create docs/README.md as documentation guide - Organized all documentation by purpose and audience - Provided clear navigation structure - Added consolidation recommendations for future improvements - Included maintenance guidelines 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Consolidated setup and troubleshooting documentation - Created SETUP_AND_TROUBLESHOOTING.md combining environment setup and dependency troubleshooting - Provides single reference for all setup needs - Includes comprehensive troubleshooting for common issues - Updated all cross-references - Updated docs/README.md to reflect consolidation - Updated REPOSITORY_STRUCTURE.md references - Updated main README.md references - Fixed references to non-existent language-specific guides - Documentation is now properly organized - Implementation guide (implementation-guide.md) covers all languages - Setup and troubleshooting combined for better user experience - API documentation kept separate for different audiences 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Pull Request Overview
This PR consolidates and updates the documentation to improve accuracy and navigation. The changes ensure proper problem counts, fix difficulty levels, and create a comprehensive documentation guide for better organization.
- Fixed total problem count from 34 to 36 and corrected difficulty level distributions
- Updated system overview with accurate problem counts and reorganized problem tables
- Created comprehensive setup and troubleshooting guide consolidating multiple documents
Reviewed Changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/SYSTEM_OVERVIEW.md | Updated problem counts and difficulty classifications, reorganized problem tables |
| docs/SETUP_AND_TROUBLESHOOTING.md | New comprehensive guide consolidating setup and troubleshooting documentation |
| docs/REPOSITORY_STRUCTURE.md | Updated file references to reflect new consolidated documentation structure |
| docs/README.md | New documentation navigation guide organizing all documentation by audience |
| docs/PROBLEM_CATALOG.md | Updated problem statistics and added missing SYS-001 problem entry |
| README.md | Updated documentation references to point to new consolidated guides |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
| | API Gateway | GQL-001 | GraphQL Federation Gateway | | ||
| | Runtime Platform | FN-001 | Serverless Function Runtime | | ||
| | Database | TS-001 | Time-Series Database | | ||
| | Web API | WEB-012, WEB-013, WEB-014 | Advanced Web API Features | |
There was a problem hiding this comment.
The description 'Advanced Web API Features' is too generic. Consider providing more specific descriptions for each problem ID or linking to the detailed catalog for clarity.
Suggested change
| | Web API | WEB-012, WEB-013, WEB-014 | Advanced Web API Features | | |
| | Web API | WEB-012 | OpenAPI 3.0 Spec Generation | | |
| | Web API | WEB-013 | WebSockets with Real-time Updates | | |
| | Web API | WEB-014 | Rate Limiting & Throttling Middleware | |
| | Authentication | AUTH-010, AUTH-011 | OAuth 2.1/OIDC, RBAC/ABAC | | ||
| | Database | DB-010, DB-011 | Money Transfer, Event Sourcing | | ||
| | Data Processing | DATA-010, DATA-011 | Stream Processing, CDC | | ||
| | Network Protocol | NET-010, NET-011 | Reverse Proxy, gRPC Service Mesh | |
There was a problem hiding this comment.
Multiple problem IDs are listed in a single row without individual descriptions. Consider separate rows for each problem or clearer indication of which description applies to which problem ID.
Suggested change
| | Network Protocol | NET-010, NET-011 | Reverse Proxy, gRPC Service Mesh | | |
| | Web API | WEB-012 | Advanced Web API Features | | |
| | Web API | WEB-013 | Advanced Web API Features | | |
| | Web API | WEB-014 | Advanced Web API Features | | |
| | Authentication | AUTH-010 | OAuth 2.1/OIDC | | |
| | Authentication | AUTH-011 | RBAC/ABAC | | |
| | Database | DB-010 | Money Transfer | | |
| | Database | DB-011 | Event Sourcing | | |
| | Data Processing | DATA-010 | Stream Processing | | |
| | Data Processing | DATA-011 | CDC | | |
| | Network Protocol | NET-010 | Reverse Proxy | | |
| | Network Protocol | NET-011 | gRPC Service Mesh | |
| If you continue to experience issues: | ||
|
|
||
| 1. Check the [GitHub Issues](https://github.com/itdojp/req2run-benchmark/issues) | ||
| 2. Join our [Discord Community](https://discord.gg/req2run) |
There was a problem hiding this comment.
The Discord invite link appears to be a placeholder or example URL. Verify this is a valid Discord invite link or update with the correct URL.
Suggested change
| 2. Join our [Discord Community](https://discord.gg/req2run) | |
| 2. Join our [Discord Community](https://discord.gg/your-valid-invite) <!-- TODO: Replace with your actual Discord invite link --> |
| 問題が続く場合： | ||
|
|
||
| 1. [GitHubイシュー](https://github.com/itdojp/req2run-benchmark/issues)を確認 | ||
| 2. [Discordコミュニティ](https://discord.gg/req2run)に参加 |
There was a problem hiding this comment.
The Discord invite link appears to be a placeholder or example URL in the Japanese section as well. Ensure this matches the verified URL from the English section.
Suggested change
| 2. [Discordコミュニティ](https://discord.gg/req2run)に参加 | |
| 2. [Discordコミュニティ](https://discord.gg/req2run-invite)に参加 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR updates and organizes the documentation to ensure accuracy and improve navigation.
Changes
📊 Updated Problem Counts
🔄 Updated System Overview
📚 Created Documentation Guide
Consolidation Recommendations
As documented in the new README, the following consolidation is recommended for future work:
Testing
Draft PR Notice
This is a draft PR to minimize CI costs during development. The PR will be marked as ready for review once all documentation updates are confirmed.