Skip to content

READMEを再構成し、詳細ドキュメントをdocs/に分離#40

Merged
harakeishi merged 5 commits intomainfrom
docs/readme-restructure
Feb 17, 2026
Merged

READMEを再構成し、詳細ドキュメントをdocs/に分離#40
harakeishi merged 5 commits intomainfrom
docs/readme-restructure

Conversation

@harakeishi
Copy link
Owner

概要

READMEを著名OSS(lazydocker, fzf, ripgrep)のパターンを参考に再構成。情報過多だったREADME(約490行)
をコンパクト(約150行)にし、詳細ドキュメントをdocs/に分離。併せて、未実装機能(Auto-cleanup、docker
compose up実行)の記載を削除し、実装と一致する内容に修正。

変更内容

  • README.mdを再構成(490行 → 150行)
    • Hero Section: ロゴ + バッジ + 一行説明のコンパクトな導入
    • The Problem: Before/After形式で問題提起と解決策を提示
    • Quick Start: 2コマンドですぐ始められるセクションを追加
    • Usage: コマンド一覧・オプションをテーブル形式に整理
    • Features: 実装済み機能のみを簡潔に列挙
    • Documentation: 詳細ドキュメントへのリンク集テーブル
  • 詳細ドキュメントをdocs/に分離
    • docs/configuration.md: 設定ファイルの全オプションリファレンス
    • docs/reserved-ports.md: 予約ポートの動作と設定例
    • docs/network-conflict.md: ネットワーク競合回避の詳細
  • 実態と乖離した記載の修正
    • Auto-cleanup(未実装)の記載を削除
    • cleanコマンド(スタブのみ)をコマンド表から削除
    • docker compose up実行の記載を削除し、手動実行を案内する形に修正
    • 出力例を日本語ログ40行超 → 英語テーブル形式の簡潔な例に差し替え
  • Directory Structureセクションを削除(内部実装詳細のため)
  • docs/plans/2026-02-17-readme-improvement-design.md: 設計ドキュメントを追加

期待すること

  • 初見のユーザーが5秒以内にツールの目的を理解できる
  • READMEがスキャンしやすく、必要な情報にすぐたどり着ける
  • 詳細を知りたいユーザーはdocs/のリンクから辿れる
  • READMEの記載が実装と一致しており、誤解を生まない

動作確認

項目 証憑(スクショなど) 備考
README.mdのマークダウンがGitHub上で正しくレンダリングされる プッシュ後にGitHubで確認
ロゴ・バッジが正しく表示される 既存のlogo.pngを参照
docs/配下の各mdファイルへのリンクが正しく遷移する 相対パスリンクを使用
docs/configuration.mdの内容が既存の設定仕様と一致する 元READMEの内容を移植
Contributors セクションが正しく表示される ALL-CONTRIBUTORS形式を維持

harakeishi and others added 5 commits February 17, 2026 21:21
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Restructure README for clarity: hero section, problem statement,
  quick start, concise usage table, and feature summary
- Extract detailed docs to separate files:
  - docs/configuration.md: full config reference
  - docs/reserved-ports.md: reserved port behavior and examples
  - docs/network-conflict.md: subnet conflict resolution details
- Remove Directory Structure section (internal detail)
- Replace verbose Japanese log output with concise English table example
- Follow lazydocker-style minimal & scannable structure

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove auto-cleanup claim (not implemented)
- Remove clean command from command table (stub only)
- Clarify that gopose generates override.yml but does not run
  docker compose up
- Update output example and descriptions accordingly

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@harakeishi harakeishi merged commit 4912acf into main Feb 17, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant