アイオス コーポレートブログ
Markdown設計書を快適にしたくて、とある試みをしてみた
皆さん、こんにちは。技術開発グループのn-ozawanです。
当社では、6月14日は創立記念日としてお休みとなります。また当日は毎年恒例のアイオスオープンというゴルフ大会が開催されます。
本題です。
皆さんは設計書を作成するのに何を利用していますか？今でもExcelやWordを利用しているプロジェクトは多いのではないでしょうか。現在、当社ではとあるシステムを内製しており、その設計書をMarkdownで記述しています。Markdownは手軽に記述出来る一方で、読み辛さやトレーサビリティがとり辛いなどの課題もあります。そんなMarkdownの課題を解消すべく、とある試みを試験導入してみましたので、今回はそのお話をしたいと思います。
目次
設計書を静的サイトで見れるようにする
導入の理由と経緯
ExcelやWordは使い勝手も良く便利な反面、バイナリデータであることから差分比較やマージにあまり向いていません。Markdownで設計書を作成すれば差分比較やマージが容易に行えるため、複数人の同時開発に有利になります。最近ではConfluenceなどのwikiベースで設計書を作成するプロジェクトもありますが、導入費用の高さから中々手が出せない企業もいるのではないでしょうか。
当社では今期より社内で利用するシステムを開発しており、開発に際していくつかのテーマを設けながら進めています。その１つが「設計書を何で作るか？」です。今回、Markdownで設計書を作成することを決定したのですが、Markdownでは以下の課題があると考えています。
- 見たい見出しへのジャンプがし辛い
大きな設計書となると、文書も長くなってきます。文書が長くなると、見たい見出しへ気軽にジャンプすることは可読性の観点で重要です。GitHubは画面右側にアウトラインが表示されるので、いつでも見出しへジャンプすることは可能です。しかし当社ではGitLabを使用しており、GitLabは見出しへのジャンプはページを一番上まで戻らないと出来ません。
- トレーサビリティがとり辛い
開発では上流工程の成果物の内容が、きちんと下流工程の成果物に反映されているかのトレーサビリティが必要です。もし、下流工程の成果物に反映されていない場合、それは仕様漏れとなり、後工程で障害となるリスクがあります。Markdownではトレーサビリティとしてリンクを貼ることは出来ますし、テーブルなどで管理することも出来ますが、手作業で行うのは少々手間ではあります。
今回試してみたこと
これまで通り記述したMarkdownを、Astroを使って静的サイトを構築しました。Astroを使ったMarkdownの取り込みは前回の記事を参照してください。デザインも読みやすさを重視とし、見出しも分かりやすくしています。また、画面右側にアウトラインを配置することにより、いつでも指定の見出しへジャンプすることが出来ます。
トレーサビリティの課題については、自動的にドキュメントとリンクを貼るプラグインを作成しました。
ステークホルダの要求から抽出した仕様を「要求仕様一覧」としてまとめ、各仕様に対してIDを採番します。そして、画面仕様書などの各仕様書へ反映する際に、その仕様の根拠となるIDをインラインコードとして記述します。Astroでビルドする際に、インラインコードで記述されたIDを検知して要求仕様一覧へリンクを貼るようにします。要求仕様一覧の静的HTMLを生成する際には、各仕様書に対してIDでgrepしてHITしたドキュメントへリンクを貼るようにしました。
これにより各仕様書と、その根拠となる要求仕様一覧に、自動的に相互リンクが貼られることになります。上流工程から下流工程へ抜け漏れなく反映されていることが確認出来るのと同時に、下流工程からその根拠となる上流工程への確認も出来るようになりました。
CI/CDにより誰でも見れるようにした
以上で十分なのですが、せっかくなのでdevelopブランチへマージされたタイミングで、Astroにて生成された静的HTMLファイルをS3にアップロードするようにしました。これにより、開発者のみならず、開発に参画していない社員たちも設計書を見れるようになります。
効果
この環境を構築するためのコストが発生したものの、以下の効果を感じました。
- Markdownが読みやすくなった
GitHubやGitLabでも十分に読めるものではありますが、色などによるメリハリを持たせることにより、よりMarkdownが見やすくなったように感じます。今回紹介しませんでしたが、テーブルのセルを結合するプラグインを導入したりと、プロジェクトの特性に合わせて色々と工夫することが出来るのも魅力的です。 - 仕様の抜け漏れを防止できる
上流工程から下流工程へ進むと仕様の抜け漏れが発生する場合があります。上流工程の成果物と、下流工程の成果物で相互リンクを貼ることにより、上流工程の仕様が抜け漏れなく反映されているのかが視覚的に分かるようになります。 - 開発者ではない人たちも手軽に見れる
GitHubやGitLabからでもアカウントさえあればMarkdownを見ることは出来ますが、開発に明るくない人（例えば業務の運用者など）はどことなくハードルを感じるものではないでしょうか。ホームページ感覚で設計書を読めるのはDevOpsの観点でも良かったと感じます。
今後の課題
今後の課題としては導入コストが挙げられます。もし、他のプロジェクトでも同じように導入するとなると、Astroのコードをメンテナス出来る要員が必要です。費用対効果を考えると、プロジェクトによっては不要な気がします。もっと簡単に扱えるようにパッケージ化する必要はあるでしょう。
また、wikiベースの設計書にあるような、第３者が設計書の記載内容にコメントを残したり、複数の人間が通話で会話しながら同時に設計書に手を入れる、などと言った柔軟なアプローチが取れません。そこはMarkdownを利用した開発に限界があるかもしれません。
おわりに
設計書の記述方法に関しても、その時代のニーズに合わせて変えていく必要があります。今回紹介した試みも完全とは言えません。wikiベースの設計にも興味はあるのですが、世の中にあるwikiアプリが沢山ありすぎてどれがいいのか迷いますね。プロジェクトによってはMicrosoftのSharePointとか使えるのでは？とも思ったりします。参画しているメンバーのスキルや、開発の運用方針なども考慮して、適切な設計書の記述方法を模索していきたいです。
ではまた。
