GitHubを中心とした開発プロセスのドキュメント管理編です
[readme.md] ドキュメントを管理する
そのリポジトリに関するドキュメントはGitHubで管理してGitHubで閲覧したい
どうして？
- 共有ファイルサーバにExcelってスタイルはOSの制約があったりするからイヤだ
- ソースとドキュメントは一元管理されるべきだと思うから
- ドキュメントもPullRequest等でレビューするべきだよ
- ドキュメントもバージョン管理したいよ
使い方
- ルートのディレクトリに
README.mdを設置する - Markdownを書いてpushする
この例はdoc/の様なディレクトリにある.mdファイルへのリンク集としてみた
[github wiki] Wikiを管理する
管理ドキュメントが増えてきたらドキュメントをWikiにしよう
特徴
- GitHub上でお手軽に作成出来る
- ブラウザで作ったWikiは
git cloneしてローカルで加筆修正することも出来る - ページの一覧が勝手に表示される
- サイドバーとフッターも書くことが出来る
使い方
- Wikiのタブを選択し、
Create the first pageボタンを押す - Markdownを書いてsubmitする
サイドバーとフッターはそれぞれ_Sidebar.md, _Footer.mdと言うMarkdownを書けば勝手に表示してくれる
ぽちぽちしているだけでこんな感じのWikiができちゃう
この例もreadmeの例と同じようにリンク集としてみた サイドバーがインデックスになっている
readmeとwikiの違い
一番違うのはREADME.mdは同一リポジトリだけど、Wikiは別リポジトリという点だと思う
両方管理するとしたら、例えばこんな観点で分けると良いんじゃあないかな
| README.md | Wiki | |
|---|---|---|
| 更新頻度 | 頻繁 | ほとんど無い |
| PullRequestに | 含めたい | 含めなくて良い |
| 管理者 | 開発者 | 例えばPOやディレクター |
| 内容 | 開発者用 | システム利用者用 |