はじめに
この記事は DMMグループ Advent Calendar 2023 の10日目の記事です。
こんにちは。動画配信事業部でフロントエンドエンジニアをしている今西(@nisshii0313)です。
ここ2年くらいはDMM TVというサービスの開発に従事しており、主に動画再生プレイヤーまわりのコンポーネントの開発および保守・運用を行っています。
最近では各種テレビやPS4、PS5でもDMM TVを視聴可能にするための開発・保守・運用を行っています。
このDMM TVですが、今年の12月でリリースから1周年を迎えることができました。
おかげさまで、徐々に新機能の追加を含めた保守・運用フェーズに移行してきています。
しかし、動画再生プレイヤーの開発知見(特に各種テレビ・PS4・PS5向け)においては「属人化問題」に直面しつつあります。
今回は、その属人化対策として、「Diátaxis」というフレームワークを用いた体系的なドキュメント整備のアプローチ方法についてご紹介します。
Diátaxisとは ~概要~
Diátaxisは、体系的なドキュメント作成に用いられるフレームワークで、ドキュメント化したい内容を次の4要素に分類することで「整備しやすさ」「読みやすさ」を両立することを目指しています。
- Tutorials
- How-To guides
- Reference
- Explanation
各要素について詳しく説明をする前に、具体的な内容(知識)について4要素で分類をし、雰囲気を掴んでみます。
その際に、知識自体の「とっつきやすさ」、つまり初学者から見た理解しやすさという軸で簡略化して考えてみます。
Diátaxisとは ~まずは簡略化して捉えてみる~
私がフロントエンドエンジニアということもあり、フロントエンド分野の知識について前述した“とっつきやすさ”を軸に軽く分類すると次の図のようになります。
さらにDiátaxisの4要素に振り分けてみると次のようになります。
TutorialsやHow-To guidesは「基礎」で、普段仕事をするために必要な実践的な内容が該当します。
一方、ReferenceやExplanationは「専門的」で、数年後のスタンダードを決めるような議論の場が該当します。
大まかに4要素の雰囲気が掴めたところで、各要素の詳細な要件やうれしい点について説明していきます。
Diátaxisとは ~各要素について~
Tutorials
Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. Tutorials are learning-oriented.
とあるように、初学者にとっての“とっつきやすさ”が求められています。ライブラリのREADMEの内容を整備するような感覚ですね。
具体的には、主に以下のような要件があります。
- 学習に必要なものを、あらかじめ十分に提供してスタートラインを揃える
- 学習フローとして詰まらないことを担保する
- 学習者目線で、それまでのフローにミスがないことを確認しやすくする
- 仮に学ぶ中でミスを犯しても、最初からやり直しやすいこと
- なるべく具体的な手順を記載する
- 誤解を招かないためにも、必要十分に書くようにする
環境をコンテナ上で用意したり、各手順で期待値のスクショを載せたり、ミスや不必要になれば立ち上げた環境ごとdownやdestroyしてもらう感覚ですね。
こうすることで、読み手にとっての学習コストを下げたり、最初の1歩のハードルを下げることができます。
How-To guides
How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are goal-oriented.
とあるように、実務上の課題とその解決策がある前提で、ケースごとに紹介していくことが求められています。ポストモーテムを書くような感覚と似ているかもしれません。
具体的には、主に以下のような要件があります。
- 課題とその解決策にフォーカスして、詳細説明などは別セクションに委ねる
- 課題とその解決策が端的に伝わるようなタイトルにする
- ある程度汎用的に活かせる課題解決のほうが好ましい
書き手にとっては散乱しがちな実装や課題解決の経緯をまとめておく場所ができ、読み手にとっては今タイムリーに必要な具体的な解決策を、タイトルから検索するだけで探すことができます。
Reference
Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.
とあるように、情報の正確性と必要十分な詳細さが求められます。世間一般的に"ドキュメント"と言われるものは、ここを網羅しているものが多いのではないでしょうか。
具体的には、主に以下のような要件があります。
- 語彙に一貫性を持たせる
- 個別具体的な説明や議論、指示、推測はノイズになるので、他箇所に委ねるか省く
- ノイズにならない程度に理解を助けるものとして、各項目に凡例を載せる
- 常に正しく、最新であることを心がける
書き手にとっては前述までで省いてきた詳細をここにまとめておくことができ、読み手にとってはHow-To guidesで事足りない場合に頼るという使い分けができます。
Explanation
Explanation is discussion that clarifies and illuminates a particular topic. Explanation is understanding-oriented.
とあるように、議論の場であることが求められます。ライブラリや提供するサービスの仕様について議論するといった、いわゆるOSSのissue内での議論やサービス開発の上流工程のイメージで良いかと思います。
具体的には、主に以下のような要件があります。
- これまでとは打って変わって、関連性のある項目の内容に積極的に触れていく
- なぜ？に答えるために、背景情報を説明する
- 議論の場として提供し、反論の余地も残しておく
- 上記を満たしながらも、他の3セクションと役割的に被らないように注意する
このセクションが存在することで、書き手同士の間で議論が生まれ、結果としてReferenceが更新されるなどの新しい知見が生み出されます。
弊チームでの取り入れ方
公式ドキュメントにも記載がありますが、Diátaxisはあくまでフレームワークとしてドキュメントの体系化を助けてくれるだけで、その活かし方はケースごとに最適な形を見つけていく必要があります。
今回の「DMM TVの再生プレイヤー部分についての開発知見(特に各種テレビ・PS4・PS5向け)」という場合ではいくつかカスタマイズしている点があるのでご紹介します。
別枠でドキュメントの歩き方(Q&A)を用意
読み手にDiátaxisの理解を求めるのは少々酷な話です。
そこで読者パターンをいくつか想定して、どこから読み進めるべきかをQ&A形式でまとめています。
How-To guidesをラベルで管理
前述したように、How-To guidesの肝としてタイトルによる検索性が挙げられていました。
ドキュメント管理ツールにもよるとは思いますが、弊社で使用している「Confluence」ではラベル機能があるので、動画の配信形式やデバイスなどのトピックごとにラベルを用意し、検索性を担保しています。
Explanationは省く
Explanationは議論の場ですが、あくまで今回やりたいことは「知見の属人化回避」です。
サービスの機能追加や仕様の議論、動画配信技術についての先進的な取り組みは別のドキュメントでまとめられているため、省きました。
まとめ
Diátaxisを使う使わないに関係なく、共同でドキュメントを整備していくには何らかのフレームワークに従わないと乱れが生じることは想像に難くないと思います。それが原因でドキュメントが形骸化していく例もこれまでに何度か見てきました。
Diátaxisは比較的理解しやすく簡単に始められるフレームワークかなと思います。ぜひ使ってみてはいかがでしょうか。
