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やディレクター
内容 | 開発者用 | システム利用者用