開発ドキュメントサイトにおけるコンテンツの種類まとめ

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

この中で、

わかりやすい開発ドキュメントサイトにするには、どうすればよいのか?

という問いについて考えることがあります。つまり「どのようなコンテンツを提供するか」という問題です。

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

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

著者
Hiroki Zenigami

テクニカルライター。開発者向けのドキュメントを書いています。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。

目次

対象とするコンテンツ

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

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

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

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

読者の種類

少し前置きが長くなってしまいますが、コンテンツを整理する前に、今度は読者について考えてみます。

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

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

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

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

習熟度製品に対する知識
初級者その製品に関する知識がほとんどない
中級者その製品に関する基本的な知識をもっている
上級者その製品を活用した実践的なアプリケーションを構築できる

コンテンツの種類まとめ

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

注意

この表でいう重要度というのは、あくまで目安になります。ここは製品によって異なるので、参考程度にしてください。

種類読者重要度内容
チュートリアル初級者★★★製品を用いた基本的なアプリケーション開発の方法を説明する
ドキュメント初〜上級者★★★製品の使い方を説明する
リファレンス中〜上級者★★★製品の詳細な仕様を示す
用語集初〜中級者★★☆読者にとってわかりづらい用語を説明する
FAQ初〜中級者★★☆読者の悩みとその解決策を示す
ショーケース初〜中級者★★☆製品で実現できることを紹介する
実装例中〜上級者★☆☆ユースケースごとの実装方法を示す
コミュニティ中〜上級者★☆☆製品を取りまくコミュニティを紹介する
プレイグラウンド初〜中級者★☆☆ウェブ上で製品を体験できるアプリケーションを提供する

重要度 ★★★ のコンテンツ

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

チュートリアル

チュートリアルの例 チュートリアルの例(Next.js)

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

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

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

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

ドキュメント

ドキュメントの例 ドキュメントの例(Contentful)

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

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

種類内容
Getting Startedはじめるとき、更新するとき等に見るもの
Basics基本的なアプリケーション開発をするために十分なもの
Advanced実践的なアプリケーション開発に役立つもの

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

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

リファレンス

リファレンスの例 リファレンスの例(Stripe)

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

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

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

重要度 ★★☆ のコンテンツ

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

用語集

用語集の例 用語集の例(Stripe)

用語集は、開発ドキュメントサイトの中で使われている用語を簡潔に説明するためのコンテンツになります。

ドキュメントを書くときは、どうしても読者が分かりづらい用語を使う必要があるときが出てきます。こんなときに、例えばStripeではツールチップで用語の概要を表示しています。

ドメイン知識が必要な製品の場合は、用語集があると読者に伝わりやすくなります。

FAQ

FAQの例 FAQの例(Stripe)

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

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

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

ショーケース

ショーケースの例 ショーケースの例(Next.js)

ショーケースというのは、その製品を使っている製品を画像などで一覧にまとめたコンテンツになります。

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

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

重要度 ★☆☆ のコンテンツ

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

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

実装例

実装例の例 実装例の例(Next.js)

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

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

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

コミュニティ

コミュニティの例 コミュニティの例(Nuxt)

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

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

例として、NuxtがModulesという形でコミュニティのページを提供しています。

プレイグラウンド

プレイグラウンドの例 プレイグラウンドの例(Stripe)

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

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

読者にあわせたコンテンツをつくる

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

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

このため、まずはじめに

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

ということをじっくりと考える必要があります。

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

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

おわりに

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

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

著者
Hiroki Zenigami

テクニカルライター。開発者向けのドキュメントを書いています。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。

\ よかったらフォローしてください /
関連記事関連書籍
人気記事
applis
アプリケーション開発について学ぶブログ
お問い合わせ
ご意見・ご質問やお仕事のご依頼などは以下よりお願いいたします
お問い合わせ
© 2020-2022 applis