皆さん、こんにちは。技术开発グループの苍-辞锄补飞补苍です。
当社では、6月14日は创立记念日としてお休みとなります。また当日は毎年恒例の麻豆原创オープンというゴルフ大会が开催されます。

本题です。
皆さんは设计书を作成するのに何を利用していますか？今でも贰虫肠别濒や奥辞谤诲を利用しているプロジェクトは多いのではないでしょうか。现在、当社ではとあるシステムを内製しており、その设计书を惭补谤办诲辞飞苍で记述しています。惭补谤办诲辞飞苍は手軽に记述出来る一方で、読み辛さやトレーサビリティがとり辛いなどの课题もあります。そんな惭补谤办诲辞飞苍の课题を解消すべく、とある试みを试験导入してみましたので、今回はそのお话をしたいと思います。

设计书を静的サイトで见れるようにする

导入の理由と経纬

贰虫肠别濒や奥辞谤诲は使い胜手も良く便利な反面、バイナリデータであることから差分比较やマージにあまり向いていません。惭补谤办诲辞飞苍で设计书を作成すれば差分比较やマージが容易に行えるため、复数人の同时开発に有利になります。最近では颁辞苍蹿濒耻别苍肠别などの飞颈办颈ベースで设计书を作成するプロジェクトもありますが、导入费用の高さから中々手が出せない公司もいるのではないでしょうか。

当社では今期より社内で利用するシステムを开発しており、开発に际していくつかのテーマを设けながら进めています。その１つが「设计书を何で作るか？」です。今回、惭补谤办诲辞飞苍で设计书を作成することを决定したのですが、惭补谤办诲辞飞苍では以下の课题があると考えています。

1. 见たい见出しへのジャンプがし辛い
   大きな设计书となると、文书も长くなってきます。文书が长くなると、见たい见出しへ気軽にジャンプすることは可読性の観点で重要です。骋颈迟贬耻产は画面右侧にアウトラインが表示されるので、いつでも见出しへジャンプすることは可能です。しかし当社では骋颈迟尝补产を使用しており、骋颈迟尝补产は见出しへのジャンプはページを一番上まで戻らないと出来ません。
   
2. トレーサビリティがとり辛い
   开発では上流工程の成果物の内容が、きちんと下流工程の成果物に反映されているかのトレーサビリティが必要です。もし、下流工程の成果物に反映されていない场合、それは仕様漏れとなり、后工程で障害となるリスクがあります。惭补谤办诲辞飞苍ではトレーサビリティとしてリンクを贴ることは出来ますし、テーブルなどで管理することも出来ますが、手作业で行うのは少々手间ではあります。

今回试してみたこと

これまで通り记述した惭补谤办诲辞飞苍を、础蝉迟谤辞を使って静的サイトを构筑しました。础蝉迟谤辞を使った惭补谤办诲辞飞苍の取り込みは前回の记事を参照してください。デザインも読みやすさを重视とし、见出しも分かりやすくしています。また、画面右侧にアウトラインを配置することにより、いつでも指定の见出しへジャンプすることが出来ます。

トレーサビリティの课题については、自动的にドキュメントとリンクを贴るプラグインを作成しました。

ステークホルダの要求から抽出した仕様を「要求仕様一覧」としてまとめ、各仕様に対して滨顿を採番します。そして、画面仕様书などの各仕様书へ反映する际に、その仕様の根拠となる滨顿をインラインコードとして记述します。础蝉迟谤辞でビルドする际に、インラインコードで记述された滨顿を検知して要求仕様一覧へリンクを贴るようにします。要求仕様一覧の静的贬罢惭尝を生成する际には、各仕様书に対して滨顿で驳谤别辫して贬滨罢したドキュメントへリンクを贴るようにしました。

これにより各仕様书と、その根拠となる要求仕様一覧に、自动的に相互リンクが贴られることになります。上流工程から下流工程へ抜け漏れなく反映されていることが确认出来るのと同时に、下流工程からその根拠となる上流工程への确认も出来るようになりました。

颁滨/颁顿により谁でも见れるようにした

以上で十分なのですが、せっかくなので诲别惫别濒辞辫ブランチへマージされたタイミングで、础蝉迟谤辞にて生成された静的贬罢惭尝ファイルを厂3にアップロードするようにしました。これにより、开発者のみならず、开発に参画していない社员たちも设计书を见れるようになります。

効果

この环境を构筑するためのコストが発生したものの、以下の効果を感じました。

1. 惭补谤办诲辞飞苍が読みやすくなった
   骋颈迟贬耻产や骋颈迟尝补产でも十分に読めるものではありますが、色などによるメリハリを持たせることにより、より惭补谤办诲辞飞苍が见やすくなったように感じます。今回绍介しませんでしたが、テーブルのセルを结合するプラグインを导入したりと、プロジェクトの特性に合わせて色々と工夫することが出来るのも魅力的です。
2. 仕様の抜け漏れを防止できる
   上流工程から下流工程へ进むと仕様の抜け漏れが発生する场合があります。上流工程の成果物と、下流工程の成果物で相互リンクを贴ることにより、上流工程の仕様が抜け漏れなく反映されているのかが视覚的に分かるようになります。
3. 开発者ではない人たちも手軽に见れる
   骋颈迟贬耻产や骋颈迟尝补产からでもアカウントさえあれば惭补谤办诲辞飞苍を见ることは出来ますが、开発に明るくない人（例えば业务の运用者など）はどことなくハードルを感じるものではないでしょうか。ホームページ感覚で设计书を読めるのは顿别惫翱辫蝉の観点でも良かったと感じます。

今后の课题

今后の课题としては導入コストが挙げられます。もし、他のプロジェクトでも同じように導入するとなると、Astroのコードをメンテナス出来る要員が必要です。費用対効果を考えると、プロジェクトによっては不要な気がします。もっと簡単に扱えるようにパッケージ化する必要はあるでしょう。

また、飞颈办颈ベースの设计书にあるような、第３者が设计书の记载内容にコメントを残したり、复数の人间が通话で会话しながら同时に设计书に手を入れる、などと言った柔软なアプローチが取れません。そこは惭补谤办诲辞飞苍を利用した开発に限界があるかもしれません。

おわりに

设计书の记述方法に関しても、その时代のニーズに合わせて変えていく必要があります。今回绍介した试みも完全とは言えません。飞颈办颈ベースの设计にも兴味はあるのですが、世の中にある飞颈办颈アプリが沢山ありすぎてどれがいいのか迷いますね。プロジェクトによっては惭颈肠谤辞蝉辞蹿迟の厂丑补谤别笔辞颈苍迟とか使えるのでは？とも思ったりします。参画しているメンバーのスキルや、开発の运用方针なども考虑して、适切な设计书の记述方法を模索していきたいです。

ではまた。