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を書けば勝手に表示してくれる
この例もreadmeの例と同じようにリンク集としてみた サイドバーがインデックスになっている
readmeとwikiの違い
一番違うのはREADME.mdは同一リポジトリだけど、Wikiは別リポジトリという点だと思う
両方管理するとしたら、例えばこんな観点で分けると良いんじゃあないかな
README.md | Wiki | |
---|---|---|
更新頻度 | 頻繁 | ほとんど無い |
PullRequestに | 含めたい | 含めなくて良い |
管理者 | 開発者 | 例えばPOやディレクター |
内容 | 開発者用 | システム利用者用 |