閉じる

より良いドキュメントを作成する

あなたはプロジェクトをスタートさせたばかりです。ドキュメントを作成しなければならないのですが、「どうしよう…」と途方に暮れています。 

確かに、最初は大変そうに見えるかもしれませんが、私たちがサポートします! 以下は、ドキュメント作成のためのドキュメントです。プロからのヒントを紹介したステップバイステップガイドになっていて、順を追ってプロセスを進めることができます。さあ、やってみましょう! 


重視すべき理由

簡単に言うと、ドキュメントとは、読んだ人が必要なことを実行できるようにするものです。ですが、とてもすばらしいことに、ドキュメントはただ何かを実行できるようにするだけでなく、もっとすごい働きをします。ドキュメントによって、ユーザーとチームができるようになることを以下にご紹介します。

精神的な消耗が減る

あまり思い悩まなくても、最小限の労力で作業を実行できます。

一貫性が生まれる

同じ情報、手順、計画を、誰が読んでも一貫した方法で利用できるようになります。

作業負荷を最小限に抑える

すばやく効率的にオンボーディングできるため、新しいチームメイトもすぐに仕事を始められます。

組織のブランディングを高める

役に立つ情報を提供することによって、社外のお客様と社内の従業員を支援する姿勢を示すことができます。 

価値を提供しないドキュメントを読む人はいません。あなたの仕事は、提供しようとする情報に対する読者の考えを整理して、なぜそれを重視する必要があるのかを伝えることです。

ドキュメントとは

ドキュメントはさまざまなものを指します。あらゆる事象について記載された一連の文書がドキュメントと言えます。ドキュメントは一般のエンドユーザーにとっては指針であったり、ソフトウェアエンジニアにとっては戦略書であったりします。技術的な文脈で言うと、ドキュメントは通常、1 つのソフトウェアに付随するテキストまたはイラストです。こういった文書は、ソフトウェアの仕組み、動作、使い方を説明するリファレンスガイドとしての役割を果たします。ソフトウェアチームであれば、製品の要件、リリースノート、設計仕様について話し合うときにドキュメントを参照することもあるでしょう。技術チームであれば、コードや API について詳しく解説し、ソフトウェア開発プロセスを記録するのにドキュメントを使用するかもしれません。外部向けのドキュメントは、システム管理者、サポートチーム、その他のエンドユーザーを対象としたマニュアルやユーザーガイドといった形式を取ることも多くあります。
 

すべてのドキュメントで、以下の 2 点を目標とする必要があります。

 

1. ユーザーに情報を伝える

2. ユーザーが何かを成し遂げられるようにする

ドキュメントを作成する場合、読み手が内容をすぐに理解できるよう、中心となるテーマ、目的、または目標を定義することから始めます。

ドキュメントの種類

すでにご説明したとおり、ドキュメントにはあらゆる形式や規模のものがあり、内部向けや外部向けのものがあります。ドキュメントの種類によって、必要な文体、語調、書式、執筆者、対象者、内容は異なります。最も一般的な種類を、以下にご紹介します。



内部向けドキュメント
team-documentation-illustration

チーム向けのドキュメント

チーム向けのドキュメントでは、チームがチームとして作業できるよう、行うべき作業をわかりやすく説明します。このようなドキュメントは、プロジェクト計画、チームスケジュール、ステータスレポート、ミーティング議事録など、チームが機能的かつ効率的に作業するために必要なあらゆる形をとります。この種類のドキュメントは、全員が同じ認識を保てるよう、詳細な内容となっています。

reference-documentation-illustration

参照ドキュメント

参照ドキュメントは、重要なトピック、プロセス、ポリシーを社内の従業員に伝えます。これには、人事部門が作成したポリシー、外部ベンダーの採用に関する法務プロセス、会社に利益をもたらすためのハウツー記事などが該当します。参照ドキュメントは、少数の執筆者が多数かつ多様な読み手向けに記述するものであるため、わかりやすい内容にすることが重要です。

project-documentation-illustration

プロジェクトドキュメント

プロジェクトドキュメントは本来プロジェクト固有で、製品開発に必要な構造をしています。これには、提案書、製品の要求仕様書、設計ガイドライン、概略図、ロードマップ、および開発に必要なその他の関連情報とプロジェクトマネージャー、エンジニア、設計者などの関係者情報が該当します。



外部向けドキュメント
system-documentation-illustration

システムドキュメント

システムドキュメントでは、コードや API、および開発中のソフトウェアで使用できるメソッドや関数、制限事項や要件について開発者やプログラマーに伝えるその他のプロセスの詳細を記述します。例として挙げた API 呼び出しと応答のようなコードスニペットが、この種類のドキュメントの中心となっています。

end-user-documentation-illustration

エンドユーザー向けドキュメント

ユーザー向けドキュメントは、最もよく見られる種類のドキュメントです。読みやすさとわかりやすさを兼ね備え、新しいバージョンのソフトウェアが出たら簡単に更新できるものである必要があります。このようなドキュメントには、「はじめにお読みください」ドキュメント、インストールガイド、管理ガイド、製品ナレッジベース、チュートリアル (数ある中でもこれが最も有益です) などがあります。また、参照ドキュメントと同様、少数の作成者が多数の消費者向けに記述するものであるため、わかりやすい内容にすることが大切です。

Including examples in your documentation offers a huge value to your audience. They serve as a bridge to help understand concepts and ideas, and ensure the reader that you do in fact know what you are talking about.

ドキュメントの作成

最終的な目標は、読み手の役に立つドキュメントを作成することです。ドキュメント作成が少しでも簡単になるよう、ドキュメント作成のためのドキュメント (メタ的!) を、チュートリアル形式でご用意しました。

 

1. 調べる

製品、プロジェクト、あるいは API について、ユーザーは何を知る必要がありますか? 分析ツールを使って検索内容を確認し、オンラインコミュニティフォーラムやディスカッショングループを見て回り、ユーザー調査やユーザビリティテストを実施しましょう。また、製品について理解し、ユーザーからの質問、新機能、ワークフローなどを簡単に説明する方法も把握します。

2. 作成を開始する

手始めに、ドキュメントで説明する内容と、その内容が読み手にとって重要な理由を明確に示します。

3. 詳細を提示する

コンテンツの概要と下書きを作成します。読み手に合った文体とトーン (人間らしく!) で、一貫性を持って簡潔に記述します。重要な詳細情報を明確に伝えましょう。

4. 書式を整える

最初から最後まで見やすくなるようにページを整えます。余分なものを取り除き、長いコンテンツには図、スクリーンショット、画像などの視覚情報を挿入して分割します。

5. レビューを実施する

誤字脱字や表現についてフィードバックを受けます。レビュワーにドキュメントの目標を理解させてください。そうすることで、わかりにくい表現や記載しそびれている手順が見つかりやすくなります。

6. 公開する

レビューと修正が終わったら、いよいよ公開準備完了です。作成したドキュメントを公開し、フィードバックやコメントを逃さないよう注意しましょう。ドキュメントは公開してしまえばそれで終わりというものではありません。

重要なポイント

ご覧のとおり、ドキュメント作成はたくさんの手順や言葉をまとめるだけの作業ではありません。そこには合理的な方法があります。ドキュメントの作成前、作成中、そして寝ているときも作成後も、以下の指針を忘れないようにしてください。 

簡潔に!

ドキュメントには、ヘルプチケットを申請しなくても作業できる、適切な量の情報を記載する必要があります。キーポイントをまとめ、オプションで読み手が詳細を確認できるようにしましょう。

ビジュアルが鍵

視覚情報は理解を助けます。製品設計、コードサンプル、製品デモ、スクリーンショット、ビデオチュートリアルなどは、読み手がコンセプト、作業方法、作業内容を完全に理解するのに大きな役割を果たします。また、レイアウト、視認性、理解しやすいデータ量にも留意してください。

読み手を理解する

ユーザー目線で考えましょう。読者について理解し、ユーザーが製品とドキュメントをどう受け止めるか想像してみましょう。ユーザーについて考えることで、何をどのように書くべきかが常にわかるようになります。 

全力で素早く取りかかる

優れたドキュメントは明確かつ簡潔で、有益な情報を提供しますが、読み手に価値をもたらすことが何よりも重要です。ドキュメント作成向けの Confluence のようなチームコラボレーションソフトウェアを活用して、情報を探し出す時間を減らし、生産的な作業のための時間を増やしましょう。

詳細を見る