効果的な技術文書を作成するための戦略

私は 1999 年にイスラエルのクファル サバにある Altec Lansing の研究開発部門で QA をしていたときから、何らかのテクニカル ライティングを行ってきました。当時、私たちは Windows ME や 2000 で動作する (息を呑む) USB オーディオ デバイスのような革新的なオーディオ関連デバイスを発売していました。それらはバグが多く、セットアップは今日のように簡単なものではありませんでした。

書類が必要でした。

ユーザーが飛び越えなければならないいくつかの困難があり、それが何であるか、エッジケースが何であるか、それらすべてを診断して修正する方法を文書化する方法が必要でした。適切にパッケージ化され、きれいにフォーマットされ、ヘルパー アプリケーションをインストールしたユーザーがアクセスできる必要がありました。 Windows で標準のヘルプ アプリケーションを作成するために使用される Robohelp アプリケーションを見つけ、インストールにヘルプ ファイルを追加しました。

QA プロセスでは、問題を特定し、重要だと思われる点を文書化し、デバイスにバンドルされているヘルプ ファイルにまとめます。当時私は 19 歳で、このようなことについての経験はまったくなく、非常に単純なプロセスでした。それにもかかわらず、それはユーザーにとって正しいことだと感じただけで、マネージャーは私にそれをやめるよう明確に指示しませんでした。

24 年が経ち、それ以来、私は数多くのプロジェクトのドキュメントを作成してきました。規模も大きくなり、そういったプロジェクトに対する見方も大きく変わりました。

良いドキュメントとは何かについていくつか考えがあるので、ご興味があればぜひ共有したいと思います。

主要なドキュメントの概念

まず、ドキュメント製品の成功にとって重要であると私が考える、より具体的なルールのセットから始めたいと思います。

• ドキュメントでは、大きなアイデアを説明するために短い言葉を使用する必要があります。そのため、より簡単な言葉で言えることを説明するために派手な言葉や複雑な文を使用しないでください。途中でユーザーを失うことになるし、ライターのエゴを使う価値はありません。

• ドキュメントでは、できる限りストーリーを伝える必要があります。物語を伝える個人的で関連性のある一連のタスクの方が、抽象的な手順のセットよりも魅力的で記憶に残るからです。

• ドキュメントは検索可能であるべきです。真剣に考えれば、これは簡単なことです。ドキュメント内の内容が見つけにくい場合、ユーザーは必要なものを見つけることができません。

• ドキュメントはほとんどの場合、より大きな戦略の一部であり、これは特にソフトウェア製品に当てはまります。これは開発者擁護というより大きなトピックに触れていますが、簡単に言うと、ドキュメントはビデオ チュートリアル、実際の使用例、ライブ テクニカル サポートによってサポートされている必要があります。

• ドキュメントはテストする必要があります。すべてが正しいと確信できるかもしれませんが、他の製品と同様、実際のユーザーがいないと確実に判断することはできません。テストして、もう一度テストしてください。

  
  

総合的なドキュメントは適切に設計された製品です

新しいプログラミング言語を学ぶと、その言語の概念やアイデアが問題解決のコツの袋に流れ込みます。それはあなたをより良いソフトウェア開発者にさせ、より意識と能力が高まるので、最終的にはより良いソフトウェアを作ることができます。

私のキャリアは複雑なもので、ソフトウェア製品の設計、ソフトウェア開発、技術サポート、開発者の擁護活動に多く携わってきました。それぞれの分野は、私の考え方や他人への接し方に影響を与えてきました。

私がテクニカル ライティング プロジェクトに取り組むときは、ユーザーが何を必要としているのかについて、この広い視野を持って取り組みます。それがドキュメントについて総合的に考える正しい方法だと思います。ドキュメントは明確に定義されたものではなく、良いドキュメントを作成するには柔軟性が必要です。

私にとって、それはユーザーについてできるだけ多くの角度から考える必要があることを意味します。何事も当然のことと考えることはできません。そうしないと、一部のユーザーを失望させ、ブランド、製品、ビジネスに悪影響を及ぼし、立ち直るのが困難になります。

ドキュメントは、多くの場合、ユーザーにとって成功するか失敗するかを左右します。

あなたが良い仕事をすれば、ユーザーはあなたの製品をうまく使いこなし、あなたのブランドの支持者になるでしょう。そうしないと、あなたのドキュメントが心に悪味を残したために、彼らは二度とあなたの製品を使用しない可能性があります。彼らはまた、他の人にも知らせます。優れたマーケティングはここから始まるので、このことを念頭に置いてください。

良いドキュメントを作る

優れたドキュメントを作成するということは、他の製品プロセスと同じようにドキュメントの作成に取り組む必要があることを意味します。

必要がある：

• ドキュメントを作成する理由を理解する
• ターゲットとなる視聴者が誰なのかを知る
• 彼らの問題点を知る
• 時間をかけてドキュメントを改善する

それぞれについて詳しく見てみましょう。

ドキュメントの理由を知るには、表面的には非常に単純な質問と回答が設定されていることがよくあります。ドキュメントを作成しているのは、そうしないとユーザーが失敗して製品を使用できなくなるからです。より深いレベルでは、あなたのユースケースに対する具体的な答えがあります。開発者ツールをお持ちですか?それが 1 つの答えです。小売デザインツールをお持ちですか?会計 SaaS 製品をお持ちですか?自動コーヒーメーカーをお持ちですか？これらはすべて別個の回答セットです。

ドキュメントの形式は、それを使用する人によって決まります。オンラインですか？アプリにバンドルされていますか？印刷されていますか？すべてのユーザーベースには他に何かが必要であり、最初からユーザーが誰であるかを明確にする必要があります。

あなたの仕事は、各ユーザーにとって何が難しいのかを把握し、ユーザー固有の問題を解決する有益なコンテンツをユーザーに届けるためのドキュメントを作成することです。

最も重要なのは、最初から正しく理解できるわけではないことを知っておく必要があります。つまり、時間の経過とともに製品が成長し、変化するにつれて、ドキュメントを保守し、更新する必要があります。できれば、これは、支援しようとしているユーザーと簡単にコミュニケーションできるようなフレームワーク内で行われるとよいでしょう。ユーザーと話し、ニーズを聞き、ドキュメントを使用して製品の使用体験をより良いものにするよう努める必要があります。

ドキュメントは成功に不可欠な部分です

ドキュメントがいかに非常に重要であるかを強調して要約します。これらがなければ、ユーザーは自立し、自分で身を守らなければなりません。

これは常に成功事例の減少、エコシステム内での製品に対する評価の低下、開発者やユーザーの不満の増加、そしてブランドや会社への悪影響を意味します。

ドキュメントはそれ自体が重要なサブ製品であり、投資であり、より広範な製品戦略の一部である必要があります。