GitHubとMarkdownを活用した開発ドキュメント管理
2021年07月27日
![](https://images.microcms-assets.io/assets/869c132a16e84706a93dbf84225d22f8/a95f5a1b42f54bdcbb4a340833eac9b1/eyecatch_007.png)
はじめに
システム開発をやっているとドキュメントの作成は、程度の差はあれども、必ず必要になります。私は、最近は開発ドキュメントは、GitHubとMarkdownを使用して管理するようにしています。今回は、このGitHubと、Markdownをベースとした開発ドキュメント管理方法について記載します。
ドキュメントを作成する意味
そもそも、なぜドキュメントを作成するのか?ということですが、システム開発におけるドキュメントは、要件定義書、基本設計書などのいわゆる仕様書、設計書等と呼ばれるものや、マニュアル等があります。今回の記事では仕様書と呼ばれるものについてです。
仕様書、設計書が必要になってくるのは大きく、
- お客様と作成するものについて合意をとる
- 一緒に開発するメンバーと作成するものの認識を合わせる
の2つの目的があると考えています。一つ目の目的の場合、私がよく携わっているシステム開発は、お客様も新規にITのビジネスを開始したいというお客様が多く、ITに詳しくないお客様が多く、あまり、要件定義書や、外部設計書、内部設計書など、ITの業界では一般的なドキュメントを作成しても、内容を理解していただくことが難しいうえ、作ったとしてもあまり喜んでもらえません。
なので、リーンキャンバスや、ユーザーストーリーマッピングを実施して、お客様の実現したいことを明確にして、作成するものの合意をとるようにしています。
2つ目の目的の場合、ドキュメントの体裁よりも、内容を理解してもらうことが重要になります。そのような場合、ドキュメントをMarkdownで作成するのは、
- 書くのが楽、ページ区切りの制約がないので、文章の構成のみを考えればよい
- テキストなので、差分管理が楽、どこが変わったのかすぐにわかる
などの点で、非常にストレスなくドキュメントの作成ができます。また、作成したMarkdownをGitHubで管理すれば
- 変更履歴や、レビューをGitHubのエコシステムですべて管理できる
- GitHubにブラウザでアクセスすればブラウザで簡単に表示できる
などのメリットもあります。
当然
- お客様が印刷したドキュメントを要求している
- ドキュメントをユーザー認証が必要とはいえ、外部のSaaSで管理するのをよしとしない
場合など、難しい場合もあります。
Markdownでドキュメントを書く
Markdownは、ドキュメントを書くのに非常に便利です。最近は、Markdownもかなり使われてきています。とはいえ、未だに、xxx.mdファイルってどうやって開くの?と質問されることもあります。記法は簡単とはいえ、ITにあまり詳しくない人にとってはなかなかなじみがありません。
おすすめのMarkdownエディタTypora
そこで私が普段使用しているのは、Typoraという無料のMarkdownエディタです。TyporaはMarkdownをライブプレビュー状態でそのまま編集できるので、Markdownの記法がわからなくても、簡単にMarkdownファイルの編集が行えます。
Markdownを書きつつ、横にプレビューが表示されるツールは多々ありますが、Typoraがすごいのは、プレビュー画面を直接編集しながらMarkdownを記載できることです。
もちろん、ソースビューなどのモードも用意されており、Markdownを記述するのに必要な機能が漏れなくついており、これが無料で使えるのは素晴らしいです。
Typora以外のMarkdownエディタだと、VSCodeを利用している人が多い気がします。厳密にはMarkdownエディタではないですが、esa.ioというドキュメント・ナレッジの共有サービスを利用していたこともありますが、esa.ioはドキュメントはMarkdownで作成します。有料のサービスですが、Gitの操作に慣れていない人は、利用するのも一つの手です。
esa.ioのようなOSSとしては、GROWIを自分でホスティングしていたこともありますが、こちらもMarkdownで記事を書けて、ホスティングできるOSSで非常に便利です。SaaSを利用できない環境の場合、ローカル環境にサーバーを立てて利用すると便利です。
MarkdownにMermaidを利用して図表を追加する
システム開発のドキュメントを作成していると、シーケンス図などの図を記載したいということが多々あります。Markdownには、画像ファイルのURLを追加することで、画像を表示できるのですが、
- 画像ファイルをどこかにあげる必要がある
- 挙げるとしても、アクセス制限などがめんどくさい
などの問題があります。
Markdownに直接図を記入するMermaid.jsというライブラリがあり、これを利用すると、下記のように、Markdown中に直接図を記入することができます。作成できるチャートは、シーケンス図や、フローチャート、クラス図、ER図など多岐にわたっており、大抵のダイアグラムが、Mermaidで直接Markdownに記述することができます。非常にお勧めです。
Mermaidで表現できない図表を挿入する
Mermaidは非常に便利なのですが、Mermaidでは、表現できない図表をMarkdownに挿入したいことがあります。そういった場合は、何等かのツールで画像ファイルを作成して、そのURLをMarkdownに追加する方法をとっています。そういった場合は、
あたりを使用していますが、どちらも無料プランで、十分に利用できます。特徴としては、draw.ioの方がダイアグラムを書く目的であれば、より高機能で、Miroはどちらかというと、ダイアグラムを書くというよりは、メンバーとコラボレーションしながら、ドキュメントを書いていくような機能が多く、リモート環境でユーザーストーリーマッピングを実施する場合などに便利です。
なお、Miroは無料のプランだと、画像のエクスポートの解像度が小さいため、Markdownから表示した場合、きれいに見えないことが多いので、無料の範囲でやるのであればdraw.ioがおすすめです。
GitHubでドキュメントを管理する
Markdownでドキュメントを作成し、そのmdファイルをGitHubにコミット&Pushします。draw.ioのXMLファイルや、エクスポートしたSVG画像ファイルも併せてGitHubで管理しています。そうすると、すべての修正がGitHub上で管理され、何がいつ修正されたのか、明確になります。
チームメンバーと、ドキュメントを編集する場合も、GitHubに登録してあれば、プルリクエストで修正内容のレビュー依頼を出すこともできますし、リポジトリをプライベートにしておけば、メンバーだけに閲覧を制限することも可能です。
ただ、GitHubは、
- GitHub上でMermaid.jsの図表が表示されない
- GitHubのデザインが左右に大きな余白があるため、横幅の大きい図が小さくなってしまう
などの、欠点があります。なので、以下のChrome拡張をインストールしています。
GitHubでMermaidを表示するChrome拡張:GitHub + Mermaid
このChrome拡張を追加すると、GitHubのmdファイル中のMermaidで作成したダイアグラムがGitHub上で表示されます。
GitHubのレイアウトをワイドにするChrome拡張:Widescreen for GitHub
このChrome拡張を追加すると、GitHubの表示がワイドになり、横幅一杯で表示されます。
最後に
Markdownとその他のツールを使用して、文章と図を作成し、それをGitHubで管理すると、非常にストレスなく、ドキュメントの作成・管理が可能です。皆さんもぜひおためしください。