DevRelを行う上でドキュメントは大事です。そこで、逆説的にこんなドキュメントは嫌だ、というものを紹介します。皆さんのドキュメントが当てはまっていないことを期待します。

ログインしないと見られない

ドキュメントは登録ユーザだけでなく、未登録ユーザにとってもサービスを使うかどうかの判断で使われます。ドキュメントを見るためだけに登録を迫るのは、開発者にとって大きなストレスです。類似サービスがログイン不要でドキュメントを読めるなら、自然とそちらを選ぶでしょう。あえて敷居を上げる意味がありません。

ログインしないといけないドキュメントはSEOにとっても不利になります。ドキュメント検索は独自のものにならざるを得ず、それは大抵Googleよりも使いづらいものでしょう。

ドキュメントがPDF

PDFはポータブルであるという利点がありますが、それを補って余りあるくらいの欠点があります。PDFはGoogleによってインデックスされない訳ではありません。しかし、どの結果であっても同一ファイルを表示します。たった一文のために数MBのPDFをダウンロードしなければなりません。コードのコピペもしづらく、デベロッパーフレンドリーなフォーマットとはとてもいえないでしょう。

PDFにも検索機能はありますが、使いやすいものではありません。複数文字列で検索できませんし、平仮名や漢字を変換して検索してくれません。PDFで公開するメリットがどこにあるのかが不明で、運営側のエゴにしか感じられません。

間違っている

ブログ記事は新鮮度が優先されるため、少し前の記事であれば間違っていても許容されます。しかしドキュメントにおいては常に最新の状態で間違っていないことが求められます。

間違っているドキュメントはアンドキュメントよりも開発者の失望を招きます。新機能をリリースしたり、SDKを更新したりする際にはドキュメントの更新も含めて管理すべきです。

アンドキュメントがある

Web APIの解説で、存在しないはずのパラメータが実行できたり、いずれか必須のパラメータなどがあるケースです。開発者はあなたのAPIに対してそこまで思い入れがありません。達成したい目的がアンドキュメントによって成し遂げられない場合、さっさと別なサービスを検討してしまうでしょう。

これは網羅性のないドキュメントについても同様です。ドキュメントを書く際にはいきなり深く掘り下げるのではなく、浅く網羅的に書き上げた後、徐々に掘り下げていくようにしましょう。満遍なく、すべての機能について同レベルなドキュメントであるべきです。

コードがエラーになる

ドキュメントが間違っているのと同様になりますが、ドキュメントに書かれているコードをコピー&ペーストで実行してエラーになるのは大きな問題です。サービス提供側の技術レベルも疑われてしまいます。

前提とするライブラリなどがある場合は、あらかじめ記述が必要でしょう。とりあえず表示されているコードを実行してエラーが出たら、開発者としては大きな落胆を感じてしまいます。

言語によってドキュメントの差異がある

英語と日本語版で内容が異なる場合などが挙げられます。翻訳は一度きりであれば大した問題はありません。問題は継続的な更新です。差分を連絡するフロー、修正するフローが確立していないと、どんどん言語ごとのドキュメント差異が生まれていきます。

これもまた間違ったドキュメントと同じです。間違った日本語ドキュメントであれば、ない方がマシです。

日本語として読みづらい

機械翻訳を使っている、技術を知らない人が書いている、または技術を知っているが読みやすい文章を知らない人が書いたドキュメントなどが該当します。ドキュメントを理解するために、頭の中で一度解析しなければならないのは相当ストレスです。

ドキュメントには正確性が求められますが、日本語としての読みやすさも維持されていなければなりません。やたらと漢字が多い、カタカナ文字が多い、隙のないドキュメントを目指すばかりに堅苦しいといったドキュメントはよくありません。

リンクを多用しすぎてコンテンツが分散している

一つのことを達成するために複数の操作が伴う場合にありがちですが、リンクで一つ一つの作業を別なドキュメントに任せてしまうのはよくありません。開発者の目線が散らばってしまい、作業に集中できなくなります。一つのドキュメントの流れの中で作業が完結するのが望ましいです。

最悪の場合、Aという作業を行うためB、C、Dをすべて行う必要があり、さらにBを行うためにはEとFをやらないといけないといったドキュメントもあります。開発者が本当にやりたかったAからほど遠くなり、強いストレスを感じるでしょう。その挙げ句、Fの作業でエラーが出てしまえば目も当てられません。

重複したコンテンツを心配するのであれば、システムで各作業の内容を埋め込み表示してあげらればいいでしょう。

専門用語ばかり使う

ドキュメントを読む開発者はあなたのサービスのエキスパートばかりではありません。むしろドキュメントを読まずに、自分のなしたいことを達成したいと考える人の方が多いはずです。そんな中、専門用語ばかりのドキュメントを見てもさっぱり意味が分からないはずです。

もしドキュメントを読むにあたって前提知識が必要なのであれば、その用語解説を行うページを設けましょう。さらに、そういった用語に対してマウスを当てるとフローティングで意味を出してあげるような仕組みがあるといいでしょう。

まとめ

皆さんのドキュメントがこういった課題を持っていないことを祈りますが、開発者としての目線で見るとこういったドキュメントはよく見かけます。いずれも失望を感じされ、他のサービスに流れてしまうでしょう。

他のサービスに流れた開発者というのは可視化しづらいものです。せっかく興味を持ってくれた開発者を逃さないためにも、ドキュメントはしっかりと整備しましょう。

---

MOONGIFTではDevRelのサポート、アウトソーシングを承っています。ドキュメントの管理、翻訳も承ります。DevRelでのお悩みについてはお気軽にお問い合わせください。