適切なメッセージを伝えるために、プロダクトマネージャーはどのようなスタイルのドキュメントを作成すべきなのか。

ドキュメンテーションは、あらゆるオープンソースプロジェクトにおいて、最も重要かつ過小評価されているコンポーネントの1つであり、軽んじられるべきではありません。

一般的に言って、ほとんどのオープンソースプロジェクトは、作者がAPIや製品のドキュメントのために効果的なドキュメント環境を作ることにあまり興味がない、できない、時間がない、という理由だけで十分な注目を集めることができません。

アプリケーションが優れていても、ドキュメントが不十分であれば、消費者はその利用を享受することができません。

しかし、何らかの理由で活用せざるを得なくなったとしても、それをうまく、自分の思い通りにできるかというと、そうではない。

優れたドキュメントを作成する方法を理解することは、他のドキュメントプロジェクトを定期的にレビューするのと同様に、かなりの量の仕事を必要とします。しかし、Docsieのために多くのドキュメントを作成した者として、私の言葉を信じてください - 自分以外の誰かが使用するコードを構築する場合、特にその人々があなたの顧客である場合、あなたの製品は十分に文書化され、フォーマットされ、動的に表示されるべきです。

チュートリアル、ハウツー、解説、リファレンスといえば、何が違うのでしょう？

多くの人は、この4つのフレーズが同じものを指していると誤解している。しかし、実際にはさまざまな意味が込められています。このように、さまざまな種類の文書が存在しますが、その中にはいくつかの重要な違いがあります：

Tutorials Documentation: これらのタイプのドキュメントは、トレーニングのために指向された情報ベースのドキュメントです。

How-To Guides/User Guides Documentation（ハウツーガイド/ユーザーガイド ドキュメンテーション）：特定の目的を達成するために、一連の手順を通じて特定の問題を解決する方法を表現した文書。

Explanation Documentation（説明文書）：ユーザーや読者が製品についてより深く理解するために、さまざまな説明や背景を説明した記事タイプのドキュメントです。

Reference Notes Documentation: このドキュメントは、様々な新機能のアップデートや使用方法についての説明をユーザーに知らせるために設計されています。このタイプのドキュメントは、開発者向けドキュメントの形で非常に「生」であることができますが、エンドユーザーが簡単に理解できる、よりユーザーフレンドリーなリリースノートに変換することも可能です。

高品質のドキュメントを作る理由

その前に、なぜ有能なドキュメントの作成が、現代社会において非常に重要でありながら過小評価されているのかを理解することが重要です。特に、オープンソースプロジェクトでは、実質的にすべての行動が公開され、その活動がプロジェクトの成功に重要な役割を果たすため、広範でよく書かれたドキュメントを利用できることは、広く普及するための最も重要な基準の1つである。

それでは、効果的なドキュメントを書くための最も重要な理由を見てみましょう。

お客様にとってより良いオンボーディングエクスペリエンスを実現することができます。

製品に関する適切な文書を顧客に提供することで、顧客が製品をより快適に使用し、その特定のガイドラインによって保護されていると感じるようになり、顧客を支援することができます。そのためには、次のことを行う必要があります：

1.アプリ内リンクや検索可能なドキュメントプラットフォームの下で、製品ドキュメントが可視化され、簡単にアクセスできるようにすること。

2.お客様が素早く簡単に答えを見つけられるような文章であること。

1つのアドバイスとして、ドキュメントは一度だけ書き、あなたの会社が新しいクライアントを迎え入れるときに何度も消化されるようにしましょう。

その結果、サポートに関する問い合わせが少なくなりました。

ドキュメントを読んで理解した顧客は、商品を購入する可能性が高くなります。顧客が何も理解できない場合、それは非常に癪に障り、代わりにあなたの製品を非難し始めるかもしれません。

お客様によっては、困ったことがあったらすぐにサポートスタッフに連絡したり、メールを送ったりすることもあるでしょう。しかし、ドキュメントが魅力的で、簡単にアクセスでき、分かりやすければ、お客様に相談しなくても自分で解決できるようになり、結果的にお客様が力を発揮することになります。

自分のチームをサポートするのに役立ちます。

堅牢なナレッジベースは、自社のチームメンバーを支援するために使用することもできます。そのため、社内チームには、新機能、計画中のロードマップ、APIドキュメントなど、全員が同じページにいるために必要なあらゆる情報を提供する必要があります。

効果的なドキュメントの書き方をステップバイステップで説明します。

文書の中身を書くことと、この活動をアレンジすることは、どのようなトーンを使うか、どうすれば文書が理解できるようになるかを決めることとは、まったく別の作業です。オライリー、優れたドキュメントの8つのルール】(https://www.oreilly.com/content/the-eight-rules-of-good-documentation/)が述べているように：

1.読み手を惹きつけるようなドキュメントを作る。

2.プロジェクトの全領域をカバーする徹底したドキュメントの作成。

3.理解しやすいスキマ素材を作る。

4.製品の活用方法をケーススタディで示すドキュメントの作成。

5.必要な部分には繰り返しが含まれるような文書を書く。

6.最新版のドキュメントを書く。

7.貢献しやすいドキュメントを書く。

8.発見しやすく、理解しやすいドキュメントを書く。

それらの要素は、ほとんどがコンテンツに関わるものです。それに続いて、この情報をどのように構造化するかという「方法」を6つのステップで説明します：

録画する内容を決める。

チュートリアルなのか、リファレンスなのか、取扱説明書なのか、解説書なのか、どのような文書を作成するのか、始める前に時間をかけて考えてみてください。

製品の性質は、作成するドキュメントの種類に直接影響することに留意してください。

フレームワークを作成する。

まずドキュメントの土台を作りましょう。最初はごく小さなもので、数人のグループで構成されるかもしれませんが、時間が経つにつれて、あなたが構築しているプラットフォーム全体が大きく、複雑になり始めます。組織構造は、定期的に見直す必要があります。

あなたはインストラクターであり、あなたのクラスで生徒がどのように学ぶかについて最終的な責任を負っていることを心に留めておいてください。生徒たちは、あなたの指示によって動きます。したがって、構造化に時間をかければかけるほど、生徒たちの努力はより成功することになります。

マルチメディアの健全な技術を常に活用する。

動画、図面、様々なスタイルを活用し、ドキュメントに直接差し込むようにしましょう。Docsie は、このプロセスを容易にするために、私たちのプラットフォームでこれらのいずれかを埋め込むことができます。

消費者が表現する情報をより理解しやすくするだけでなく、素晴らしい検索エンジン最適化を実現し、ダイナミックなドキュメントの結果、より多くの高品質なリードを獲得することにつながります。

![]（https://cdn.docsie.io/workspace_8D5W1pxgb7Jq3oZO7/doc_IDYTWOaZCuq9mWwra/file_Tp5KRnREeB4BWVdBn/679dc5ee-07ce-4579-b1e1-39f8afa64dceSnag_73f0470f.png）

検索可能であることを確認する。

ナレッジベース・プラットフォームによって検索機能に違いがあります。基本的な検索しかできず、セグメントへのドリルダウンができないもの（何千ものファイルがない場合は技術的に問題ありません）もあれば、ドキュメントだけでなくユーザー名でも検索できるクエリオプションを提供するものもあります。

しかし、一つだけ重要なことがあります。それは、素早く検索できるツールを活用することです。アプリ内に搭載された検索機能を使えば、アプリを離れることなく、簡単にファイルを検索し、プレビューを見ることができます。

Docsieは、動的に検索可能なナビゲーションを持ち、簡単に情報にアクセスできるようにします。

常に改善と更新を心がける

ドキュメントの作成と利用は、それを作成した人や利益を得た人からすぐに忘れられてしまうため、困難です。また、ドキュメントは、その旅路の中で様々な困難に直面します。

時間が経つと、古い文書がモニターの画面の下の方に残りやすくなり、フォルダ構造が墓地のようになります。

そのため、古いドキュメントに目を通し、改善するようにしましょう。Docsieでは、高度なバージョン管理システムにより、シンプルかつ簡単にアップデートを行うことができます。

![]（https://cdn.docsie.io/workspace_8D5W1pxgb7Jq3oZO7/doc_IDYTWOaZCuq9mWwra/file_ICAmxGtiRnaADNias/228e6de7-cf2c-4104-ac68-5b9d5909d572Snag_73f34a8b.png）

最終的な感想です：

効果的なドキュメントの書き方について、もっと知りたいと思いませんか？ソフトウェアドキュメンテーションの専門家にとっては、ここに大量のブログと情報があります。