DevRelの主な施策(その1)「ドキュメント整備」

DevRelの主な施策(その1)「ドキュメント整備」

今回から何回かに分けて、DevRelで行う施策について紹介します。まずごく基本であるドキュメント整備です。

ドキュメントの種類

一言でドキュメントと言っても幾つかの種類に分かれます。主に以下になります。

  1. 使い方
  2. APIドキュメント
  3. ヘルプ

初見のユーザが一番必要とするのは使い方です。そのため、わかりやすいGetting Startedのドキュメントを作る必要があります。

ドキュメントを見て軽く使い始めたユーザが自分のやりたいことをしようと思った時に必要になるのがAPIドキュメントです。そのためAPIドキュメントはURLやモデル、オブジェクトが整然と並んでいるのはもちろんのこと、ユーザ視点に立った上で、ユーザが実装したい内容に合わせて記述されている必要があります。いくら内容があってもユーザが探しづらいドキュメントは嫌われます。

最後に実際に使っていく上で必要になるのがヘルプです。とはいえ、良くある質問で記述されている内容は利用者視点に立っていないことが多く、そもそも良くある質問であれば他のドキュメント中に反映されているべきでしょう。

また、画面の項目に関するヘルプであれば、画面の中にクエスチョンマークを表示しておいて、マウスオーバーでツールチップによる説明を表示するといった対応もできます。そのため、最近ではヘルプをあえて作らずにQ&Aで答えられる場所を設ける傾向があります。

最後にドキュメントは検索が自由にできている必要があります。そのためにはGoogleなどのクローラーから検索できたり、サイト内検索においてはドキュメントの種類やプログラミング言語でのフィルタリングなどもサポートされている方がいいでしょう。ただしGoogleの検索に比べるとサイト内検索は機能が貧弱であることもあって、開発者にとっては使い勝手の悪いサイトと受け止められてしまうことも多いようです。

UPDATE

アップデートを受け取る

メールにてDevRelに関するニュース、アップデートをお送りします。

Contact is below.