開発ドキュメントを書くときの参考になるサイト5選

私は仕事で開発者向けにドキュメントを書いています。文章を書くのはもちろんですが、よりよい開発ドキュメントにするために、「コンテンツのあり方」についても考えることがあります。

「わかりやすい開発ドキュメントにはどんなコンテンツが必要なのか」「レイアウトはどうするべきか」など、コンテンツについて考える上で参考になるサイトを調べたので、この記事でまとめてみます。

よりよい開発ドキュメントづくりの参考になればうれしいです。

開発ドキュメントの定義

この記事でいう開発ドキュメントとは、開発者向けにライブラリやフレームワーク、APIなどを提供している製品についてのドキュメントをいいます。

著者
Hiroki Zenigami

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

目次

わかりやすい開発ドキュメントの条件

参考になりそうなサイトを見つけるにあたって、まず「わかりやすい開発ドキュメントの条件」を考えてみました。読み手として開発ドキュメントを読む上で、次の3つはほしいと思ったので、条件としました。

  • スムーズに移動できるナビゲーションがあること
  • 形を問わず、わかりやすいコンテンツを提供していること
  • 文章が読みやすいこと

参考になるサイト

上で書いた条件をもとに、開発者向けにドキュメントを提供しているたくさんのサイトを見てみました。その中で、次の5つがとても参考になると思ったので紹介します。

  1. Next.js
  2. Nuxt
  3. Stripe
  4. Contentful
  5. Terraform

ひとつずつ見ていきます。

1. Next.js

Next.jsのトップページ Next.jsのトップページ

Next.jsの開発ドキュメントは「まずチュートリアルを読んでね」というメッセージがいろんなところから伝わり、サイトの目的が明確なところが参考になります。

初学者にひとつ目の成功体験を達成してもらうことが今後の利用につながるので、実利にかなった目的だといえます。

コンテンツもチュートリアルとドキュメント、APIリファレンスが分かれていて、開発者の習熟度に応じて見るべきコンテンツがわかりやすいところもポイントです。

2. Nuxt

Nuxtのトップページ Nuxtのトップページ

Nuxtの開発ドキュメントはコンテンツの種類が豊富で、デザインもきれいです。ドキュメントやチュートリアルの他に、ショーケースやユースケースごとの実装例もあります。

プラットフォームごとへのデプロイの方法や、モジュールへのリンク集もまとめてあります。

Nuxtのサイトは英語・日本語・フランス語の3カ国語で利用できます。多言語対応をしているサイトなら、この点も参考になりそうです。

3. Stripe

Stripeのトップページ Stripeのトップページ

Stripeの開発ドキュメントは、図を用いてフローなどをわかりやすく説明しているところが参考になります。Stripeは開発者にとって理解が難しい製品ではありますが、ツールチップなどを用いた「わかりやすさへの工夫」が読み取れます。

デザインもきれいで、製品が多い場合のサイト設計に役立ちそうです。その他に、Stripe Payment Elementのように、機能をウェブ上で体験できるプレイグラウンドもあります。

4. Contentful

Contentfulのトップページ Contentfulのトップページ

Contentfulは「Concepts」として、各コンテンツにおける共通の概念を初めに提示しています。例えばAPIの全体像やドメインモデルなどがConceptsで紹介されています。

ナビゲーションもわかりやすく、ページの上部には各コンテンツへのリンクがあり、どのページを読んでいても共通しています。

JavaScriptやRubyなど、言語・プラットフォームごとの使い方についてもまとめてあり、開発者の課題を解決する工夫が見てとれます。

5. Terraform

Terraformのトップページ Terraformのトップページ

TerraformというよりHashicorp製品について全体的にいえるのですが、チュートリアルがとても充実しています。Hashicorp Learnというサイトがあり、初学者向けにコンテンツを提供しています。

例えば「Terraformを利用してAWSにインフラを構築する方法」といったコンテンツがチュートリアル形式で公開されています。

参考になるサイトから得た学び

前述した5つのサイトを通して、次のような学びを得ました。

  • 初学者向けにチュートリアルを提供している。また、チュートリアルへの導線が明確になっている
  • 習熟度に応じて「チュートリアル・ドキュメント・APIリファレンス」とコンテンツが分けられている
  • ショーケースで採用事例を提示している
  • ユースケースごとの実装例を提供している
  • 用語の概要をツールチップで表示したり、プレイグラウンドを用意するなどの工夫がある

おわりに

開発ドキュメントを書くときの参考になるサイトを5つ紹介しました。その中で、チュートリアルの提供など、分かりやすいサイトにはいくつか共通する項目があるという学びがありました。

よりよい開発ドキュメントを書く上での参考になればうれしいです。

著者
Hiroki Zenigami

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

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