優れたドキュメントを作成するための入門書
公開: 2015-06-06
この投稿は、ゲスト著者のJeffMatsonによって寄稿されました。 Jeffは、GravityFormsのドキュメントの責任者です。 彼はHeartbeatControl WordPressプラグインの作成者であり、90年代のファンです。
多くの場合、ドキュメントは開発プロセスの中で最も過小評価されている部分です。 WordPressコミュニティのロックスターを見るとき、私たちは通常、開発者、デザイナー、マーケターを調べます。 すべてがスムーズに実行されるように血、汗、涙を流したドキュメンテーションライターについてはほとんど知られていません。
この投稿は、開発者が何を考えているのか、そして存在するコードの背後にある真の意味を解読するために、コードの無限の行をじっと見つめている人々についてです。
優れたドキュメントは言葉以上のものです
優れたドキュメント作成者は、取扱説明書以上のものを提供し、経験を提供します。 私は優れたドキュメンター、指導された初心者を知っています、そしてそれらの間の最大の違いはそれを読んでいる人々の頭脳を理解することです。 小説のように、ドキュメンテーションには、読者が理解しているよりも多くの情報に興味を持ち、摂取し続けるフローがあります。
質の高いドキュメントは、それを読む可能性が最も高いユーザーを対象としています。 また、それを読む可能性が低い人のための参照ポイントを提供します。 たとえば、特定のフックを文書化する場合、通常、開発者がそれを読んでいると想定されますが、開発経験がほとんどない人はどうでしょうか。
優れたドキュメンテーションライターは、サポートに連絡して説明する必要なしに、正しい方向にさらにプッシュする必要がある人のための参照ポイントを提供します。
ドキュメントはあなたが思っているよりも大きな影響を及ぼします
ほとんどの場合、ドキュメントを無視し、ドキュメントを取得できなくなるまで、ドキュメントを無限の深淵に押し込みます。 場合によっては同じことで有罪になります。 それらの人々が気付いていないのは、プラグインやテーマが文書化されていないままになっていると、ユーザーエクスペリエンスが低下するということです。
最も一般的なサポートチケットを見てみましょう。 その問題をより適切に文書化した場合、それらのチケットは完全になくなりますか？ おそらくそうではありません。 この問題に関するチケットを減らし、あなたやあなたのサポートエージェントの生産性を向上させますか？ 私はそれを保証します。 より少ないサポートチケットを使用できると思います。
前述したように、ドキュメントはユーザーエクスペリエンスに劇的な影響を与えます。 ユーザーが情報を簡単かつ効率的に見つけることができれば、ユーザーは自分の時間とあなたの時間を節約できます。 世界の平均寿命は66。57年であり、ユーザーは、不十分に書かれたドキュメントをいじくり回すよりも、自分の人生で何か他のことをしたいと思っています。
顧客は、あなたがドキュメントにかなりの時間と労力を費やしていることに気付いた場合、意識的かどうかにかかわらず、あなたに感謝するでしょう。 優れたドキュメントは、最初の販売後にそれらを気にかけていることを示しています。
苦労して稼いだお金を使い、すぐに購入を後悔した後、高くて乾燥したままになったことはありますか？ 私たちは皆持っていると思います。 適切なドキュメントがあれば、その気持ちを顧客に伝えることを避けることができます。
どうすればより良いドキュメントを書くことができますか？
最初のステップは、それを避けるのをやめることです。 一度上手になれば、ドキュメントを書くことはあなたが思っているよりも楽しい経験になります。 実際、それは第二の性質になります。 世界の他のすべてのように、練習は完璧になります。
ドキュメントを次のレベルに引き上げることを決定するときに実行したい最初のステップの1つは、問題点を特定することです。 何について連絡がありますか？ やみくもに物事について書き始めると、あなたが書いていることがあなたが望むほどの影響を与えていないことに気付くかもしれません。
私が発見した最良の手法の1つは、文書化されているチケットとそうでないチケットの数を追跡し、文書化されていないチケットをカテゴリに分類することです。 このように、あなたはあなたの問題点をよりよくターゲットにして、彼らがそうあるべきであるほど役に立たないかもしれない部分を修正することができます。
作成するドキュメントを決定したら、対象読者を決定し、それを開発者、ユーザー、およびパワーユーザーに分類する必要があります。 これは、その特定のオーディエンスに対応するのに役立ちます。 これらのユーザーをターゲットにする方法については、少し後で説明します。
次に、ドキュメントを分解します。 開発者の場合は、生の情報（受け入れられた引数、戻り値など）、特定の例、およびユースケースに分解する必要があります。 ユーザーにとって最善の行動はウォークスルーです。 どんなに些細なことでも、彼らがとる必要のあるすべてのステップは重要です。
道のあらゆる段階で彼らにそれを綴りなさい。 パワーユーザー向けのドキュメント化は、ユーザーシナリオと非常に似ていますが、より構造化され、スキャン可能です。 明確にしますが、前の手順を最初に読まなくても、必要な場所に簡単にジャンプできるようにします。
より良いドキュメンテーションを書く芸術
ドキュメントを書く技術に関しては、聴衆を最も的を絞った方法で書くだけでなく、彼らが理解できるとわかっている簡単な言葉を使用してください。 これの最も良い理由の1つは、翻訳によるものです。 Google翻訳は優れた仕事をしますが、5年生の簡単な語彙は、大学院の論文に含まれているものよりもはるかに簡単に翻訳できます。
コンテンツ内で、関連するコンテンツにリンクすることを恐れないでください。 これにより、複数のドキュメントを繰り返すことを回避できるだけでなく、特定の主題に関する詳細情報が必要な場合に読者が後戻りできるようになります。 結局のところ、あなたの主な目標は、ユーザーを幸せにし、時間を節約することです。
公開ボタンを押しても、ドキュメント化プロセスは停止しません。 戻って、必要に応じてすべてのドキュメントを改訂します。 ドキュメントが公開された直後に、戻って、追跡したサポートチケットが減少し、その特定の記事へのトラフィックが増加したかどうかを確認します。 通常、記事へのトラフィックが増えている場合は、それが役立ちます。 トラフィックが増えてもサポートチケットの数が同じである場合は、その記事を調べて理由を確認することをお勧めします。
私たちが学んだこと
まず、ここまで進んだ後、私たちのほとんどが当たり前と思っているドキュメントを書いている塹壕にいる人々に、より良い感謝を持ってくれることを願っています。 それは本当に、生活のためのドキュメンテーションを書く私たちの多くが本当に楽しんで、何時間も費やす芸術形式です。
また、既存のドキュメントとそれをどのように改善できるかについて、この記事から離れてください。 適切なドキュメントは非常にやりがいがあり、一度実践すれば、実際に書くのはとても楽しいものになります。
早めに文書化し、頻繁に文書化します。 優れた製品は優れたコード以上のものであり、美しく文書化されています。