このサイトについて

このサイトは、テクニカルライティングを行う人のためのガイド集です。

運営理念

このサイトは完成を目的にするのではなく、目の前の課題をいち早く解決することを目的にしています。 そのため、書きかけのコンテンツや不足している点、書きかけの箇所が複数あります。改善をすばやく繰り返し、途中でも公開し常に更新続けます。

ドキュメントについて

プロダクトを多くのユーザに使ってもらうためには、良いプロダクトを開発することと同時に、使い方がすぐにわかるドキュメントを用意することが必要です。 ドキュメントが読みやすい、探しやすいということはユーザ体験の向上につながります。 そのため、ドキュメントはおまけではなくサービスの一部であるということを意識してください。

ドキュメントの価値と可能性

充実したドキュメントを準備することにより、導入を検討しているお客様に対して、検討時の判断材料として提供することができます。また、ドキュメントが開発者を手助けすることにより、退会を防ぐ役割もはたします。

また、サポートチームがお客様の問い合わせに対してすでに準備されたドキュメントを渡すことにより、サポートの運用コストを下げることが可能です。

開発チームとしても、第１次情報をドキュメントに集めることにより、最新で正しい情報に素早くアクセスすることができ、無駄なコミュニケーションが省ける分、学習コストを抑えることができます。

責務

PdM of Documentationの責務

いくらドキュメントがわかりやすく書かれていても、それを載せているWebサイトが使いづらければ読む人は幸せになりません。そのため、ドキュメントサイトは使いやすくするために様々な工夫をしたり、機能を提供する必要があります。 また、良いドキュメントを完成させるには、Dev/CS等複数のチームと連携しなくてはいけません。コミュニケーションプランを設計し、無駄のない適切なコミュニケーションを取りましょう。

テクニカルライターの責務

まずはお客様にとってわかりやすいドキュメントを作成します。

大切にすること

共通言語を利用する

言語の共通化を行い、メンバー間では同じ言語を同じ意味で理解し合えるようにしましょう。 用語集・ユビキタス言語を制定し、新規でドキュメントを作成する際、またコミュニケーションを取る際に非常に効力を発揮します。 言語には多くの選択肢があり、それぞれイメージする概念が異なると混乱することもありますが、ユビキタス言語があれば進むべき方向性を見定める一つの手助けとなり、チームの効率を上げてくれます。

自分で手を動かす

ドキュメントを執筆する際は、対象となる機能の仕様について、ミーティング、あるいは仕様書を受け取ってインプットします。 ただ、仕様の内容だけを見て書くのではなく、極力自分たちで手を動かし確認した上で執筆してください。 実際にドキュメントを読む人たちは、何かを実装することが目的なはずです。執筆する際は読者の目線を意識しながら自分で手を動かし、作業をしてください。

初めての人にも伝わるか考える

初めてプロダクトを利用する人でもわかりやすいように書くことを意識してください。 初めての方が読むと誤解してしまう文章になっている場合や、XXXという単語が出てきた場合等で、それまで触れてなかったら内容が理解できない可能性があります。 我々は読む人の理解度コントロールはできないので、初めてドキュメントを読む方のことも想定しながら書くことを心がけてください。

お問合せ先

このサイトについてのお問い合わせは、TwitterよりDMを送ってください。