開発者が必要としているドキュメントとは

はじめに

今回はドキュメントのお話です。DevRelでは、開発者をサポートし、彼らの生産性が最大化するように支援しなければなりません。その最初の一歩とも言えるのがドキュメントです。

開発者にサービスを使ってもらう上で、ドキュメントは超重要です。理想型としてはドキュメントがなくても使いこなせる状態なのでしょうが、そんなことはまずありません。何かトラブルがあってもすぐに解決できるのはドキュメントがあるからです。

なぜドキュメントが必要なのか

開発者の立場になれば、ドキュメントがない状態は考えられないでしょう。しかし、自分たちがサービスを提供する立場になると、ドキュメント不足や、どういったドキュメントを提供すれば良いのか分からないといった意見がよく聞かれます。

Supabaseのドキュメント例

ドキュメントは、開発者が安心して開発するためのガイドラインです。提示されている内容に沿って進めれば、トラブルなく開発できることが期待されます。もちろん、ドキュメントに載っていることだけを実装するわけではないので、自分たちのロジックの中で使えばエラーが出たり、うまく動かないこともあります。そうしたときにはドキュメントに答えを求めます。ドキュメントを読めば、何らかの答えが得られると期待されているのです。

そのため、以下のような状況は避けるべきです。

ドキュメントが不足している

不足しているかどうかは開発者の主観なので、人によって過不足の感じ方は違います。しかし、「よくあるワークフローに関するドキュメントがない」「システムで扱うモデルの説明がない」といった状態は良くありません。「ユーザー」というモデル1つとっても、その意味はサービスによって異なります。開発者自身の場合もあれば、開発者が作成したアプリの利用者といった場合もあります。意味を取り違えることがないよう、適切に説明しなければなりません。

ドキュメント不足が発生する理由は主に2つあります。1つは、ドキュメントを作成するリソース不足です。開発とドキュメント作成のリソースバランスが悪く、機能開発にばかり重点が置かれていると、ドキュメントまで手が回りません。もう1つは、認知不足です。提供元が「当たり前だ」と感じてしまうことでドキュメント漏れが発生するパターンです。このギャップは、ジュニアレベルの開発者に試してもらい、手が止まってしまうタイミングなどを計測すると分かりやすいでしょう。

ドキュメントが間違っている

不足しているのも問題ですが、ドキュメントが間違っているのは話になりません。「ドキュメントはガイドライン」と説明しましたが、その当てにすべきガイドラインが間違っていれば、開発者体験としては最悪でしょう。ドキュメントの間違いに2〜3回直面すれば、もう使う気にならなくなります。それくらいドキュメントのミスは問題です。

ドキュメントのミスが発生する理由としては、ドキュメントと実コードの距離があると考えられます。多くの場合、テクニカルライターは開発者ほど技術スキルが高くないため、システムのコードを見ながらドキュメントを書くのは非効率的であったり、ミスが発生しがちです。ドキュメントとシステムのコードを同じリポジトリで管理するか、Docstringとしてシステムのコード内にドキュメントが書かれている方が望ましいでしょう。

更新されていない

ドキュメントが古いまま放置されていないでしょうか。もちろん、システムが更新されていなければドキュメントもそのままになりがちです。しかし技術は進化しているので、ブラウザバージョンやプログラミング言語のバージョンも変化しているはずです。ずっと昔のブラウザアイコンが並んでいたりすると、サービス自体放置されているのではないかと訝しんでしまいます。

ドキュメントは生ものです。放置しているとあっという間に腐ってしまいます。そうならないためには、定期的な見直しが欠かせません。しかし、それを難しくしている要因もいくつかあります。まず「更新するのに一定のコストがかかる」ということです。最初の段階で頑張りすぎて大量のドキュメントを作ると、更新コストが捻出できなくなります。

もう1つは「ドキュメントのつながりによって、どこを修正すれば良いのか分からなくなる」ことです。同じような文言が複数の箇所で使われていると、1箇所を修正して終わりにはなりません。色々な場所を見返しているうちに修正漏れが発生します。類似の記述はしないよう注意するか、同じ文言は共通テンプレート化するといった対応がお勧めです。

ドキュメントの種類

開発者向けのドキュメントには、どういったものがあるでしょうか。ここではフランス発のドキュメント作成手法「Diátaxis」に従って紹介します。

• チュートリアル
• ハウツーガイド
• リファレンス
• 解説

Diátaxis

チュートリアル

チュートリアルはレッスンです。手取り足取り説明することで開発者に学習してもらうためのドキュメントです。内容は実践的で、開発者は内容に合わせて何か(コーディングやシステム設定など)を行います。

チュートリアルはドキュメントなので、実際に教える人が近くにいるわけではありません。そのため、ドキュメントだけで課題をこなせるように、分かりやすく書かれていなければなりません。

ハウツーガイド

ある状況に置かれているユーザーを助け、実用的な指示を提供します。その内容に沿って進めることで現実における目標や課題を解決します。

ハウツーガイドは、すでにスキルを持っている開発者を対象にします。チュートリアルが学習を目的とするのに対して、ハウツーガイドは仕事や実践で役立つのことを目的としています。

リファレンス

リファレンスは、開発者が正しく行動するために必要な技術的な説明を行います。リファレンスは事実ベースで書かれており、それを正しく解釈して行動に活かせるかは開発者次第になります。

解説

解説は、コンテキストと背景を説明します。チュートリアルで書かれている内容を補足したり、ハウツーガイドで書かれている内容を補足して説明したりします。

例えば、チュートリアルでは「安全のためHTTPSを使用します」と書かれている場合、解説の中でより詳しくHTTPSのメリットやデメリットを説明します。解説は元文書からリンクします。

それぞれの文書の関係

チュートリアルとハウツーガイドは、開発者が何をするか(アクション)に関係します。リファレンスと解説は、開発者が何を知るか(知識)に関係します。

さらに、チュートリアルと解説は「開発者の学習(スキルの習得)」に貢献します。一方でハウツーガイドとリファレンスは「開発者の仕事(スキルの利用、応用)」に貢献します。

良いドキュメントとは

良いドキュメントを提供するためには、まず以下を適切に設定しましょう。

• 誰: 対象とする開発者
• 手段: どんなドキュメントを提供するか
• ゴール: 読み終わった開発者がどうあって欲しいか

誰に提供するのか

対象とする開発者に対して、そのレベルに応じた最適なコンテンツを提供しましょう。あらゆるレベルの開発者に最適なコンテンツであるのは難しいため、事前に対象とする前提知識や技術レベルを設定する必要があります。

どんなドキュメントを提供するか

先ほどの例で言えば、チュートリアル/ハウツーガイド/リファレンス/解説の4つのいずれかになるでしょう。

読み終わった開発者がどうあって欲しいか

学習目的であれば、次は実践的に利用していくフェーズに入って欲しいでしょう。仕事の助けになるものであれば、不具合を解消してすぐに仕事に戻れるようにしなければなりません。

次のアクションを適切に促せれば、開発者は安心してドキュメントを読み進められます。ドキュメントによっては、意外と次のステップが分からずにドン詰まってしまうものも少なくありません。

ドキュメントとAIの関係

最近注目されているAIは、ドキュメントの分野でも使われています。ここでは、いくつか例を紹介します。

Cloudflare

Cloudflareのドキュメントでは「llms.txt」と「llms-full.txt」を提供しています。これはLLM向けに読み込ませることで、より質の良い回答が期待できるように作られているファイルです。Markdownで書かれており、llms.txtはリンクのみ、llms-full.txtはドキュメント全体が記されています。

Cloudflareの「llms.txt」

ドキュメントサイトでは、こうしたllms-txt/llms-full.txtを提供することで、LLMフレンドリーなコンテンツ提供ができるようになるでしょう。

Mintlify

「Mintlify」はドキュメントをLLMで生成(提案ベース)するサービスです。APIリファレンスやナレッジベース、SDKライブラリ、ChangeLogといったドキュメントに対応しています。また、ドキュメントに基づいたチャットボットも提供します。

Mintlify

開発フローにドキュメントを組み込む

個人的にお勧めしたいのは、開発フローの中にドキュメントを組み込むことです。最近ではモノレポ(複数のプロジェクトやサービスのコードを単一のリポジトリで管理する開発手法)な開発スタイルが増えており、フロントエンドとサーバーサイド、そしてドキュメントまで1つのリポジトリで管理するようになっています。

こうすることで、機能を開発した際にドキュメントも修正してマージするフローが実現します。ベースになるドキュメントは開発者自身が記述し、マージ後にテクニカルライターによる修正を入れれば良いでしょう。

ドキュメントはDocstringのようなメソッドの上に記述するものもあれば、リファレンスのように別なドキュメントの場合もあるでしょう。いずれの場合にも、コードとドキュメントの修正を1つのワークフローに取り入れることで乖離防止につながるはずです。

ドキュメントの翻訳について

あくまでも個人的な意見ですが、ドキュメントの多言語展開についてはLLMや機械翻訳に任せるべきだと考えています。機械翻訳の品質が上がってきており、まだ若干変な部分はあるけれど、十分読めるようになっています。そして、機械翻訳は原文が更新されれば、すぐに追従できます。

ドキュメントの翻訳は一度だけであれば問題ありません。しかし、更新となると大きな負担になります。修正部分を見つけ、翻訳に適合させるのは簡単ではありません。かと言って、翻訳せずに放置すれば、それは間違ったドキュメントになってしまいます。そのため、機械翻訳で済ませるという選択肢がお勧めです。

おわりに

DevRelにおいてドキュメントは重要ですが、良いドキュメントに出会うことは意外と多くありません。そして、開発者に選ばれているサービスの多くはドキュメントが充実しています。

AIに注目が集まる昨今ですが、その入力データとなるのがドキュメントです。品質の高い、十分な量のドキュメントを提供することで、レスポンスも正しいものになります。ぜひDevRelのファーストステップとして、ドキュメントの充実に力を入れてください。