私はテクニカルライターとして仕事をしています。文章を書くのはもちろんですが、これまでプロダクトマネージャーやエンジニアだったという経験を生かして、開発ドキュメントサイトの構成やコンテンツについても考えることがあります。

この中で、「わかりやすい開発ドキュメントサイトにするには、どうすればよいのか？」という問いについて考えることがあります。つまり「どのようなコンテンツを提供するか」という問題です。

このことについて、ひとことで「開発ドキュメントサイト」といっても、いわゆるドキュメントの他に、チュートリアルやリファレンスといった、いろんなコンテンツがあると思います。

このことをふまえて、開発ドキュメントサイトに必要なコンテンツを整理してみました。開発ドキュメントサイトをつくろうと思ったときに、「どういうコンテンツがあればいいのか」ということを考えるときの参考になればと思います。

Hiroki Zenigami

テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。

Follow @zenizh

開発ドキュメントサイトにおけるコンテンツを整理するにあたって、まずどういうコンテンツがあるかを洗い出してみました。これについては、以前「開発ドキュメントサイトをつくるときの参考になるサイト」という記事を書きました。

この中で、開発ドキュメントサイトには次のようなコンテンツがある、ということを学びました。

• チュートリアル
• ドキュメント
• リファレンス
• 用語集
• FAQ
• ショーケース
• 実装例
• コミュニティ
• プレイグラウンド

こういったコンテンツが、どんな読者に向けたコンテンツなのかを整理していきます。

少し前置きが長くなってしまいますが、コンテンツを整理する前に、今度は読者について考えてみます。開発ドキュメントサイトを見る読者には、いろんな層があると思います。例えば初学者や中級者などですね。この層によって、見るコンテンツは大きく変わってきます。

例えば初学者は、製品に関する知識がまだほとんどないので、例えばチュートリアルのようなコンテンツを見ると思います。一方で上級者になってくると、チュートリアル系のコンテンツはほとんど見ないでしょう。

このような感じで、読者の習熟度によって開発ドキュメントサイトの中で見るコンテンツというのは大きく変わってきます。つまりコンテンツを考える前に、そもそも「どういった読者が存在し得るのか」ということを知っておく必要があります。

この記事では、開発ドキュメントサイトを読む読者の分類について、次のように分けています。この初級者・中級者・上級者という分類で、今度はコンテンツの方を整理していきます。

それでは、開発ドキュメントサイトにおけるコンテンツの種類と、その対象となる読者・重要度・目的を表でまとめてみました。

それではまず、重要度の高いのコンテンツを見ていきます。このチュートリアルとドキュメント、リファレンスというのは、開発ドキュメントサイトにはとても重要な立ち位置にあります。

チュートリアルは、基本的には初心者向けのコンテンツになってきます。内容としては、製品を用いた基本的なアプリケーション開発の方法について説明します。

読者が製品に定着するには、読者自身の「開発を通した成功体験の積み重ね」というものがすごく大切になってきます。このため、製品をはじめて利用する読者にとって「ひとつ目の成功体験を積んでもらう」、ということが大きな目的になってきます。

また、例えばチュートリアルの中でドキュメントやリファレンスへのリンクを貼ることで、開発ドキュメントサイト全体の構成を知ってもらう、ということにも役立ちます。

Next.jsやTerraformのように、チュートリアルへの導線を強調している開発ドキュメントサイトもたくさんあります。

ドキュメントは、チュートリアルを終えた人向けのコンテンツになります。主な目的としては「製品の使い方を説明する」ということになってくると思います。「いわゆるドキュメント」というとこれを想像するような、基本的なコンテンツになります。

ドキュメントの性質は、大きく分けると次の3つに分かれます。

この3つは、読者や利用頻度が変わってきます。例えば、Getting Startedにはインストール方法やアップグレードガイドなどが当てはまりますが、これらは頻繁に見るページではないと思います。一方で、Advancedの内容は、初級者の読者には難しすぎてよくわからないかもしれません。

こういったページをひとつのコンテンツとしてまぜてしまうと、読者は何を見ればいいかわからず、開発体験が下がってしまう可能性があります。

リファレンスは、製品のより詳細な仕様について書いたものになります。例としては、StripeのAPIリファレンスがあります。

リファレンスは、実際の開発において、悩みを解決するときにピンポイントで見るようなものになっています。製品によっては、「リファレンスがないと開発できない」というケースもあるでしょう。

リファレンスを提供できるような製品である場合は、リファレンスを提供することが必須になってくると思います。

次に重要度が中くらいのコンテンツを見ていきます。ここで紹介しているコンテンツは、どれも初級者にとっては重要なコンテンツになるので、コストをかけられるのであれば積極的に検討したいものになります。

用語集は、開発ドキュメントサイトの中で使われている用語を簡潔に説明するためのコンテンツになります。ドキュメントを書くときは、どうしても読者が分かりづらい用語を使う必要があるときが出てきます。

こんなときに、例えばStripeではツールチップで用語の概要を表示しています。ドメイン知識が必要な製品の場合は、用語集があると読者に伝わりやすくなります。

FAQは、読者の悩みを起点にしたコンテンツになります。読者の悩みに対して一次回答をしつつ、あわせてドキュメントやリファレンスへのリンクを貼ります。こうすることで、読者は自分の悩みをベースに解決策を見つけることができます。

例えばStripeもFAQというコンテンツをもっています。こんな感じで、よくある質問がある場合はFAQ をつくると、読者の利便性も上がりますし、問い合わせに回答するコストも下がります。

FAQに関しては検索性というものがとても大切になってくるので、そういう意味で開発・運用コストも高くなってしまいます。

ショーケースというのは、その製品を使っている製品を画像などで一覧にまとめたコンテンツになります。「その製品を使うかどうか」というのは、つまり「つくりたいものを実現できるかどうか」が大切になるのですが、この導入事例を画像で提供すると、読者にとってとてもイメージしやすくなります。

このショーケースは、開発者だけではなく、企画担当者のようなビジネスメンバーにも参考になります。例えばNext.jsもショーケースを提供しています。

最後に、重要度の低いコンテンツを見ていきます。ここで紹介するコンテンツは、もちろんあった方がよいですが、ここまでで紹介したチュートリアルや用語集などのコンテンツの方が、重要度はずっと高いです。

特定の読者層に対する開発体験を高めたいときなどに、導入を検討するとよさそうです。

基本的なアプリケーション開発の外に出て、発展的な内容を開発しようとすると、ドキュメントの内容だけでは難しいことも出てきてしまいます。そんなときに、実装例があると開発者にとって参考になります。代表的なユースケースごとに実装例があるといいでしょう。

実装例はとても有用なコンテンツではありますが、一方で実際にコードを書いたり、あるいは「セキュリティ上の問題がないか」を考える必要があるなど、提供コストが大きくなってしまいます。

実装例についても、Next.jsがコンテンツとして公開しています。

コミュニティというのは、その製品を用いたライブラリなどを紹介するコンテンツになります。コミュニティのページを提供することは、もちろん利便性につながります。また、「製品自体の活発さ」というのも伝わります。

あとはコミュニティ向けにガイドラインをあらかじめ提供しておくと、コミュニティにいくらかの規律が生まれてきます。例として、NuxtがModulesという形でコミュニティのページを提供しています。

プレイグランドは、ウェブ上で製品を試すことのできる機能を提供します。特に初学者にとっては、ウェブ上で手軽に製品について体験できると、理解がとても進むというメリットがあります。一方で、やはり提供コストが大きくなってきます。

製品の中で、特にインパクトの大きい機能についてはプレイグランドを提供することも検討するとよさそうです。例えばStripeはPayment Elementというプレイグランドを提供しています。

ここまでで、開発ドキュメントサイトにおけるコンテンツの種類を整理してきました。この中では重要度について書きました。

ただ、最初にも述べましたが、読者というのは製品によって大きく異なります。大切なのは、その読者にあわせたコンテンツを提供することになります。

このため、まずはじめに、次のことについてじっくりと考える必要があります。

• 読者は誰なのか
• 読者は開発ドキュメントサイト上でどんな悩みを解決したいのか

例えば製品が初心者向けなら優しく丁寧に教えてあげたり、上級者向けの製品であれば前提知識を省略しつつ深い内容のコンテンツを提供する、といった感じです。

このように読者にあわせたコンテンツを作る、ということが大切になってくると思います。

この記事では、読者のレベルをもとにコンテンツを整理しました。その中でチュートリアルとドキュメント、リファレンスが重要だという話をしました。

まずは読者を理解した上で、読者が解決したい課題に応じて柔軟にコンテンツを設計できればと思います。

テクニカルライティング

【2023年】テクニカルライティングの本でおすすめの3冊を紹介します

2023-4-2

プロダクト開発

【2023年】エンジニアの本でおすすめの5冊を紹介します

2023-4-2

情報発信

エンジニアのための技術ブログの始め方を解説します【2023年】

2023-8-20