はじめに

システム開発をやっているとドキュメントの作成は、程度の差はあれども、必ず必要になります。私は、最近は開発ドキュメントは、GitHubとMarkdownを使用して管理するようにしています。今回は、このGitHubと、Markdownをベースとした開発ドキュメント管理方法について記載します。

ドキュメントを作成する意味

そもそも、なぜドキュメントを作成するのか？ということですが、システム開発におけるドキュメントは、要件定義書、基本設計書などのいわゆる仕様書、設計書等と呼ばれるものや、マニュアル等があります。今回の記事では仕様書と呼ばれるものについてです。
仕様書、設計書が必要になってくるのは大きく、

• お客様と作成するものについて合意をとる
• 一緒に開発するメンバーと作成するものの認識を合わせる

の２つの目的があると考えています。一つ目の目的の場合、私がよく携わっているシステム開発は、お客様も新規にITのビジネスを開始したいというお客様が多く、ITに詳しくないお客様が多く、あまり、要件定義書や、外部設計書、内部設計書など、ITの業界では一般的なドキュメントを作成しても、内容を理解していただくことが難しいうえ、作ったとしてもあまり喜んでもらえません。
なので、リーンキャンバスや、ユーザーストーリーマッピングを実施して、お客様の実現したいことを明確にして、作成するものの合意をとるようにしています。
２つ目の目的の場合、ドキュメントの体裁よりも、内容を理解してもらうことが重要になります。そのような場合、ドキュメントを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

あたりを使用していますが、どちらも無料プランで、十分に利用できます。特徴としては、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で管理すると、非常にストレスなく、ドキュメントの作成・管理が可能です。皆さんもぜひおためしください。