ドキュメントについての知見をまとめる
Isanaプロダクト開発でドキュメントを書かないとどうなるか
どうすればドキュメントがかけるようになるか
- トップダウンでドキュメントが必須だと明確にチームに伝える
- 開発する上で書く必要のあるドキュメントの種類を明確にする
- SSOT(Single Source Of Truth)を意識してドキュメントを更新し続ける
- チャットの履歴を一定期間しか残さない
開発する上で書く必要のあるドキュメントの種類を明確にする
要求・仕様と実装のドキュメントを分ける例
- Requirement(要求)・Specification(仕様): ビジネスサイドから見たプロダクトが満たすべき要求を書く
- ユーザにとってはどのように実装されるかは興味がない
- 例としてはPRD(Product Requirements Document)がある
- System Design(設計): 要求・仕様を満たすためにどのように実装するか開発者からみた視点のドキュメント
- 例としてはDesign Docがある
SSOT(Single Source Of Truth)を意識してドキュメントを更新し続ける
- Documentation is the single source of truth (SSOT)
- 機能の要件・仕様は修正があったらかならずドキュメントも修正する
チャットの履歴を一定期間しか残さない
- GitLabはLet your Slack or chat messages expire quicklyとし、チャットのメッセージを一定期間しか残さないようにしている
- ドキュメントには以下の種類がある
- ストック情報: 要求や仕様などまとまった情報
- フロー情報: チャットなどでやりとりされる短い保存を目的としない情報
- チャットはフロー情報
- ここをいつまでも検索できるようにするとチャットで話した仕様が本仕様となってしまう
- 検索が難しい
- SSOTを満たさない
- チャットの履歴を一定期間しか残さないようにして検索不可能にしてストック情報を残すように強制的に促す
Isananotion と情報管理、あるいは階層整理欲求と非階層整理の両立
notion と情報管理、あるいは階層整理欲求と非階層整理の両立
- 階層整理型WiKiはスケールしない - 橋本商会
- ドキュメントツールの中には階層整理の形で設計されたものも多いが、階層分類というのは「どこに分類したらいいかわからない」という、いわゆる「こうもり問題」に苛まれることが多い。
- 階層型と、 Scrapbox のような非階層型とは対立するものではない
- 一長一短で並立する関係
- 一覧性が欲しい時に階層型は便利
階層と非階層の両立としての notion
ある組織が管理したいドキュメントのうち、階層で管理したいものとそうでないものは併存し得る
notion というツールに分があるのは、その双方を混在させずに管理できる点にある
notion は大きな階層と、その節々でデータベースという小さな非階層を併存させた構造を取る
- notion の基本構造は階層整理
- すべてのページは階層のどこかに位置することを基本としており、画面左側のメニュー部分には、常に全体の階層が表示されている。
- 階層を伴わない整理機能「データベース」
- RDB のレコードのような形でページが保存されていて、それをテーブル、カンバン、カレンダーなど、好きなビューを切り替えながら一覧できる機能
- ページにはタグなどのメタ情報を複数付加することができ、それをキーにしてビューを構成する。
- 全体で検索をかければ、階層内のページも、各データベース内のページも同様にヒットする
Isana目的に沿ったDocumentation as Codeをいかにして実現していくか
目的に沿ったDocumentation as Codeをいかにして実現していくか
Documentation as Code
- システム開発の近くにドキュメント作成の仕組みを置く
- 開発サイクルの中にドキュメント作成を統合する
- システムとドキュメントの乖離を小さくする
- あくまでも文化的なはなし
継続的ドキュメンテーション
IsanaDiátaxis
- tutorials,
- how-to guides
- technical reference
- explanation.
tutorials
チュートリアルは、初心者が製品を使いこなすための基本的な能力を身につけるためのものでなければなりません。
また、チュートリアルは、学習者に有意義で達成可能なことをさせることで、その製品で成功することを示す必要があります。
つまり、チュートリアルはレッスンなのです。理論的な知識ではなく、実践的な技術に関わるので、それを学ぶというよりは、どのように学ぶかに関わるレッスンなのです。
チュートリアルを終えた学習者は、他の文書や製品そのものを理解し始めることができるはずです。
製品にとって、チュートリアルは新しい学習者をユーザーに変えます。不十分なチュートリアルは、プロジェクトが新しいユーザーを獲得するのを妨げることになります。
The tutorial as a lesson
授業は、教師と生徒の関係で成り立っています。この種の学習はすべて、生徒が行うことを通して学習が行われます。
教える際に提示される事実や説明は、生徒が何を学ぶかにはほとんど関係がない。重要なのは、教師が生徒に何をさせるかである。
私たちの目的では、レッスンは学習体験です。もし、学習者に学習体験を提供できていなければ、チュートリアルは必要な役割を果たしていないことになります。
先生の義務
教師には、生徒が何を学ぶか、それを学ぶために生徒が何をするか、そして生徒が成功するかという責任があります。生徒の責任は、注意深く、教師の指示にできる限り従うことだけである。生徒には、学習、理解、記憶する責任はありません。この契約における学習者の義務は、指示通りに行動することのみです。
同時に、生徒たちに課す運動も、そうでなければなりません。
- 意義のあること - 生徒が達成感を持つことが必要です。
- 成功 - 生徒がそれを完了することができる必要があります。
- 論理的 - 学習者の進むべき道筋が理にかなっていること
- 実用的な完成度 - 生徒が慣れ親しむ必要のあるすべての動作、概念、ツールに触れることができる必要があります。
チュートリアルの問題
一般に、チュートリアルはドキュメントの中で最も弱い部分であり、最も誤解されやすく、最もうまくやるのが難しい部分です。ほとんどのソフトウェアプロジェクトは、チュートリアルが貧弱であるか、存在しないかのどちらかです。
理想的なレッスンでは、教師はその場にいて、生徒と対話し、生徒の反応に応えます。書かれたチュートリアルは、これの完璧な代用品とは程遠いものです。
チュートリアルの作成と維持に必要な作業量は、ドキュメントの他の部分に必要な作業量よりもはるかに多くなっています。多くの場合、製品自体が急速に進化するため、チュートリアルが必要な機能を確実に果たすために、すべての作業を再度行う必要があります。
最後に、チュートリアルのように改訂が必要なドキュメントが他にないことにお気づきでしょう。リファレンスやハウツーガイドは、製品に変更があった場合にのみ変更する必要がありますが、その場合でも、通常はその一部だけを変更する必要があります。チュートリアルの場合、生徒の学習体験をより良くする方法を思いついたので、レッスン全体を完全に書き直すべきだという結論に達するかもしれません。
how-to guides
ハウツーガイドとは、現実の問題を解決するために必要な手順を読者に示す指示書です。ハウツーガイドは目標指向である。
ハウツーガイドはレシピのようなもので、特定の目的を達成するための手順を読者に案内するものだと考えてよいでしょう。
例えば、レーダーアレイの校正方法、pytestでのフィクスチャの使い方、再接続のバックオフポリシーの設定方法などです。一方、Webアプリケーションの構築方法はそうではありません。それは特定の目標や問題に対処するものではなく、広大でオープンエンドなスキルの領域なのです。
ハウツーガイドが重要なのは、ユーザーが何かを達成できるようにする必要があるからだけではありません。文書内のハウツーガイドのリストは、その製品が実際に何ができるかを示すフレームとして役立ちます。豊富なハウツーガイドのリストは、その製品の能力を示唆するものです。
もし、ハウツーガイドがよく書かれていて、適切なテーマを扱っていれば、ハウツーガイドはドキュメントの中で最もよく読まれるセクションになる可能性があります。
reference
参考資料は、機械の技術的な説明と操作方法です。参考資料は、情報重視のものです。
リファレンスガイドの唯一の目的は、できるだけ簡潔に、整然と記述することです。チュートリアルやハウツーガイドの内容がユーザーのニーズによって導かれるのに対して、リファレンス資料は説明する製品によって導かれるのです。
ソフトウェアの場合、リファレンスガイドは、API、クラス、関数など、ソフトウェアそのものとその使い方を説明するものです。
ユーザーがリファレンスを必要とするのは、真実と確実性、つまり仕事をするための確固たる土台を必要としているからです。優れたテクニカルレファレンスは、ユーザーが自信を持って仕事をするために不可欠です。
Reference as description
参考文献は渋く、ポイントを押さえたものであるべきだ。参考文献はほとんど読まないで、参考にするものである。
参考文献には疑いや曖昧さがあってはならず、完全に権威のあるものでなければならない。
参考文献は地図のようなものだ。地図は、その土地について知っておくべきことを、その土地に出かけて行って自分で確認することなく教えてくれる。リファレンスガイドは、製品とその内部機構について同じ目的を果たす。
リファレンスはタスクの実行方法を示そうとすべきではないが、何かがどのように機能するか、あるいは正しい使い方を説明することは可能であり、しばしば必要とされるものである。
参考資料の中には（APIドキュメントなど）、説明するソフトウェアによって自動的に生成されるものがありますが、これはコードに忠実であることを保証するための強力な方法です。
explanation
解説とは、特定のトピックを明確にし、明らかにするための議論である。説明は、理解志向である。
解説は、読者の理解を明確にし、深め、広げるものである。
チュートリアルやハウツーガイドのように、ユーザーが何をするのかに関心があるわけではありません。リファレンス資料のように機械にクローズアップしたものでもありません。より高い視点から、さまざまな角度からアプローチするドキュメントです。
そうすることで、説明が議論になり、よりリラックスして自由に何かを考えることができるようになるのです。説明は、物事を結びつけるものです。製品から離れたところで読んでも意味のあるドキュメントです。
解説の価値と位置づけ
Explanation and understanding
解説は、他の3つの形式の文書と異なり、ユーザーの実践や仕事に直接関わるものではありません。そのため、重要性が低いとみなされることもあります。それは間違いです。他の3つよりも緊急性が低いかもしれませんが、重要性が低いわけではありません。それは贅沢なことではありません。ある技術を実践している人は、その技術に対する理解なしにはいられないでしょうし、それを織りなすのに役立つ説明資料を必要とします。
ヨーロッパのほとんどの言語では、理解を意味する言葉のルーツは、「保持する」「つかむ」という意味の言葉と共通しています。これは「理解」の重要な要素であり、何かを保持すること、あるいはそれを所有することができるようになることです。これは、ある技術を習得するために必要な他の要素を統合し、安全に自分のものにするためのものです。
理解は単に説明から得られるものではありません。しかし、説明は、すべてをまとめるのに役立つ網を形成するために必要なのです。それがなければ、実践者の技術に関する知識はゆるく、断片的でもろいものとなり、その実践は不安なものとなってしまうのです。
解説とその境界線
また、「解説しなければならない」という考え方もあまり見かけません。その代わり、説明は他のセクションに小分けに散りばめられている傾向があります。
良い説明文を書くのは、必ずしも簡単ではありません。どこから手をつければいいのか。また、どこで結論を出せばいいのかも明確ではありません。書き手に多くの可能性を与えてしまうような、オープンエンドなところがあるのです。
チュートリアル、ハウツーガイド、リファレンスはすべて、ユーザーが学ぶべきこと、ユーザーが達成すべきタスク、あるいは単に機械そのものの範囲によって、その範囲が明確に定義されているものである。
説明の場合、現実の、あるいは想像上の「なぜ」という問いかけがあると、プロンプトとして役立ちます。そうでなければ、妥当な範囲を示す線を引いて、それで満足するしかないでしょう。
この考え方を利用したドキュメンテーションツール
ツールでは、わかりやすく少し分類名を変えている。
Tutorials -> Get started
Explanation -> Background
Isana
チームのスピードを上げるための大原則
- ノイズを減らす
- 情報を一ヶ所に集める
整理をがんばらないというアプローチで上記を実現する
- Flow 型と Stock 型の記事を理解する
記事のストック・フローの分類と検索 - 基本は Flow 型の記事にする
- 議事録カテゴリは出来るだけ作らない
- Slack に流れていく情報も Flow 型の記事にする
- 使い続けられる情報を Stock 記事として引き上げる
コラム
今では信じられないかもしれませんが、1990 年代の Yahoo! JAPAN は、人間のスタッフがウェブサイトの情報を収集してカテゴリ分類して登録する、ディレクトリ型検索サービスでした5。今はロボット型検索が使われているのは周知のとおりです。
そのため Stock 型の記事だけを作り続けるといずれ破綻することは、1 歴史が証明していると言えます（やや大げさ）。
Isana
負担を減らす工夫
- 仕様書の項目を減らす
- 仕様書フォーマットの統一
- 仕様書の命名規則を決める
- 統一されたフォーマットに沿ったテンプレートの作成
- 管理方法の明示化・単純化
- 仕様書作成・更新・廃止プロセスの明示化
- 仕様書の具体例の作成
- 仕様書を書くときに迷いそうなときに参照するガイドの作成または作成の依頼
以下notionを用いたフォーマット例
解決したい問題となぜやるのか
実際に起きている問題を記載する
目標となる指標がある場合は、指標も書くと尚良
言語定義
仕様書内で利用する言葉を定義し認識を揃える
社員なら知っているであろうと思う言葉も記載することを推奨
ユーザーストーリー
ユーザーストーリーを記載し開発メンバーと何をつくるか認識を合わせ考慮漏れを発見する
ユーザーストーリーはデータベースで管理する
データベースのプロパティは任意で追加してもよいが、ステータスが開発が終わった時点で非表示または削除することを推奨
仕様詳細
システムの制約やロジックを記載する
開発者が設計時に作成するもの・お客様やスタッフが知っているべき情報等は、ここには記載しない
システムの制約とロジック
システムに関する制約や価格の計算方法などのロジックの詳細を記載する
文章が長くなる場合は、表にまとめて記載する
実例を記載することを推奨
関連
仕様書に関連するメンテナンスされないフロー情報やリンクを記載する
具体的には、仕様作成時のメモ・FAQ・図・議事録・QA成果物・JIRAやFigmaのリンクなど
アプローチ
- Pdmを巻き込む
- 仕様書のオーナーはPdM
- 運用ルールやフォーマットを決める際は複数のPdMを巻き込もう
- 全員呼ぶのは無理なので時間の都合が付く数人ではじめるでよい
- 小さくはじめる
- いきなりカバレッジ100%を目指さない
- 作れるところからはじめる
IsanaState of DevOps 2021
- 製品・サービスの重要なユースケースを文書化
システムに関する文書が重要であり、ユースケースは読者がその情報やシステムを活用することを可能にします。 - 既存のドキュメントを更新・編集するための明確なガイドラインを作成する
文書作成の仕事の多くは、既存のコンテンツを維持することです。チームメンバーが、不正確な情報や古くなった情報を更新・削除する方法を知っていれば、システムが変化してもドキュメントの品質を維持することができます。 - 所有者を明確にする
質の高いドキュメントを作成するチーム
は、ドキュメントの所有権が明確に定義されている可能性が高い。所有権によって、新しいコンテンツを書く責任、既存のコンテンツの更新や変更の検証を行う責任が明確になります。質の高いドキュメントを作成しているチームは、自分たちが携わるアプリケーションのすべての主要な機能についてドキュメントが作成されていると述べている傾向があります。
また、明確な所有権によって、このような広い範囲をカバーすることができます。 - ソフトウェア開発プロセスの一部として、ドキュメンテーションを含める
ドキュメントを作成し、システムの変化に合わせて更新しているチームは、より質の高いドキュメントを作成しています。テストと同様に、ドキュメントの作成とメンテナンスは、パフォーマンスの高いソフトウェア開発プロセスの不可欠な部分です。
高いパフォーマンスのソフトウェア開発プロセスの不可欠な要素です。 - 業績評価や昇進の際に、ドキュメンテーションの仕事を評価する
評価は、文書全体の品質と相関があります。ドキュメントの作成と維持は、ソフトウェアエンジニアリングの仕事の中核であり、そのような扱いをすることで品質が向上します。
その他、質の高いドキュメンテーションをサポートする資料として、以下のようなものがあることがわかりました。
- ドキュメントの書き方、メンテナンスの仕方に関するトレーニング
- コードサンプルや未完成のドキュメントに対する自動化されたテスト
- ドキュメンテーションのスタイルガイド、グローバルな読者に向けたライティングのためのガイドなどのガイドライン
ドキュメンテーションは、DevOpsの機能をうまく実装するための基礎となるものです。質の高いドキュメントは、セキュリティや信頼性など、個々のDevOps機能への投資の成果を増幅させる。
クラウドの完全活用など、個々のDevOps機能に対する投資の成果を高めることができます。高品質のドキュメントをサポートするプラクティスを導入することは、より強力な技術的能力と高いSDOパフォーマンスによって報われるのです。
Isana
良い仕様書とは
- コミュニケーション・サーチコストを削減する
- PM <-> チームメンバーの無駄なコミュニケーションが減る
- 関連ドキュメントを探す手間が省ける
- （頻繁な仕様変更が起きても）Slack の海に潜る必要がなくなる
- 開発がカオスに陥るのを防ぐ
- 追加で開発される機能が減り、終盤のカオスを防げる
- 自分が何を開発しているのかを誰もが把握している
- リリースまでの工期を劇的に短縮する
- エンジニアの開発設計が正確になる
- リリース直前の QA の工数が削減される
- 最終的な成果物の品質を向上させる
- 適当な機能の振る舞いが世にリリースされるのを防ぐ
- チームのモチベーションを増大させる
- チームの Why / What / How を定義しモチベーションをあげる
仕様書に含めたい 14 の項目
- プロジェクト発起に至った背景・解決したい問題を伝える
- 検証したい仮説・達成したいことを簡単にまとめる
- プロジェクトの概略を 1-2 行でまとめる
- 計測する KPI と期待する動きをまとめる
- 実験用フラグ名・バリアント情報・振り分け% 等を記載する
- すべてのリンクを仕様にまとめる
- 「結果」欄：ローンチ後の検証結果を記載する
- 現在の UIUX を軽くまとめる
- 開発仕様：バックエンド側：を記載する
- 開発仕様：フロントエンド（クライアント）側：を記載する
- 開発仕様：トラッキング：を記載する
- QA 関連ドキュメント・質問事項をまとめるスペースを作る
- その他備考・関連部署への周知スケジュールなどをまとめる
- メンバーリストを追記する
Isana
議事録やアイディアメモなどもビジネスドキュメントもGitHub内で作成・共有している。
GitHubの全社導入を決めた理由
- 業務プロセスとドキュメンテーションを一本化できる
- Slack通知が他と比べて利便性が高い
- 差分管理が出来るため歴史的経緯を追いやすくなる
- システムが安定しておりセキュリティ水準も高い
具体的な利用方法
Code活用事例：会社基本情報の公開
ゆめみさんがやっているようなイメージに近いかも
Discussions活用事例：アジェンダと議事録の共有
Discussionつかったことないのでイメージがわかない
Issues活用事例：コーポレートへの振込依頼
経理関係のタスクをissueで運用するのはユニーク
Isana
どのようなときDesign Docsを書くか
- 開発完了までに数sprintを要する
- いくつかの実装方法が考えられる
- 技術的であったりドメイン的に新規のものや慣れていないものを扱う
運用
- テンプレート通りに書く必要はない
- Goal/Non-Goalはそれぞれ箇条書きで3行以内にまとめる
- 議論が発散するのを防ぐ
- Alternative Solution sectionは無理してでも書く
- 出戻り発生時のコストを抑え
- 一度書いたらメンテしない
- あえてSSoTを保証しない運用
- 開発時のスナップショットとして割り切る
- レビューや承認フローなどは特に設けない
- 書いた人がレビューしてほしければ個別に判断して依頼する
テンプレートの例
Overview
A high level summary that every engineer at the company should understand and use to decide if it’s useful for them to read the rest of the doc. It should be 3 paragraphs max.
Context
A description of the problem at hand, why this project is necessary, what people need to know to assess this project, and how it fits into the technical strategy, product strategy, or the team’s quarterly goals.
Scope
A description of the scope of this doc.
Goal
The Goals section should:
– describe the user-driven impact of your project — where your user might be another engineering team or even another technical system
– specify how to measure success using metrics — bonus points if you can link to a dashboard that tracks those metrics
Non-Goal
Non-Goals are equally important to describe which problems you won’t be fixing so everyone is on the same page.
Solution / Technical Architecture
Try to walk through a user story to concretize this. Feel free to include many sub-sections and diagrams.
Provide a big picture first, then fill in lots of details. Aim for a world where you can write this, then take a vacation on some deserted island, and another engineer on the team can just read it and implement the solution as you described.
System Context Diagrams
In many docs a system-context-diagram can be very useful. Such a diagram shows the system as part of the larger technical landscape and allows readers to contextualize the new design given its environment that they are already familiar with.
APIs
Systems that store data should likely discuss how and in what rough form this happens. Similar to the advice on APIs, and for the same reasons, copy-pasting complete schema definitions should be avoided. Instead focus on the parts that are relevant to the design and its trade-offs.
Data Storage
Systems that store data should likely discuss how and in what rough form this happens. Similar to the advice on APIs, and for the same reasons, copy-pasting complete schema definitions should be avoided. Instead focus on the parts that are relevant to the design and its trade-offs.
Alternative Solution
What else did you consider when coming up with the solution above? What are the pros and cons of the alternatives? Have you considered buying a 3rd-party solution — or using an open source one — that solves this problem as opposed to building your own?
Milestones
A list of measurable checkpoints, so your PM and your manager’s manager can skim it and know roughly when different parts of the project will be done. I encourage you to break the project down into major user-facing milestones if the project is more than 1 month long.
Use calendar dates so you take into account unrelated delays, vacations, meetings, and so on. It should look something like this:
Start Date: June 7, 2018
Milestone 1 — New system MVP running in dark-mode: June 28, 2018
Milestone 2 – Retire old system: July 4th, 2018
End Date: Add feature X, Y, Z to new system: July 14th, 2018
Add an [Update] subsection here if the ETA of some of these milestone changes, so the stakeholders can easily see the most up-to-date estimates.