製品ドキュメントとソフトウェアドキュメントの違いは？心配しないでください、これらは同じものです！

プロダクトチームとソフトウェアチームには、ドキュメントという共通の悩みがあります。

製品ドキュメントとは、製品のワークフローやユーザーインターフェイスを説明する、ユーザー向けのマニュアルやガイドを指します。一般的なユーザーがこの製品を使って生産性を上げるにはどうしたらいいのか？その意味で、プロダクト・ドキュメントはソフトウェア製品に使われることもあります。

ソフトウェアドキュメントとは、ソフトウェア製品の基礎技術、前提条件、および設定可能な属性のことを指します。IT管理者は、ソフトウェア製品をどのように設定し、監視し、ホストし、ユーザーに配備するのか。特に、複数のバージョンやブランチが混在している場合、この種のドキュメントは重要です。

ある意味、製品ドキュメントは、車の運転の仕方を教えるようなものです。ハンドルで車を回し、アクセルペダルで車を動かし、ブレーキペダルで車を止める。ソフトウェアのドキュメントは、車の仕組みを教えるものです。車輪はフロントアクスルに接続され、フロントタイヤを回転させて走行コースを変え、アクセルはエンジンへの空気の流れを良くし、燃料を多く取り込み、トルクや馬力を発生させます。

どちらのドキュメントも重要です。一つはユーザーを教育するもので、もう一つは管理者や開発者を教育するものです。車の運転方法を教えるのは素晴らしいことですが、もし誰も車の仕組みを知らなかったら、車が故障したときにどうなるでしょうか？

製品とソフトウェアのドキュメントの細かな相違点

製品とソフトウェアのドキュメントには、注意しなければならない細かな違いがあります：

ソフトウェアや製品のドキュメントを作成する：ターゲットオーディエンス、ペルソナ

製品ドキュメントは、ユーザーという単一の読者を対象にしています。ユーザーが技術的な知識を持っていないことを前提に、専門用語は極力使わず、平易な英語でコミュニケーションします。技術者としての見習い期間と大学の学位取得のように、理論や概念的な知識にはあまり焦点を当てず、物事の進め方について教育するものです。

ソフトウェアドキュメントは、IT管理者、エンジニア、開発者を対象としています。ソフトウェアの設計やアーキテクチャ、コマンドラインの設定方法、APIや統合のサポート、データ管理やレポート、ネットワークのトポロジーなど、基本的にはマシンを動かすための歯車を網羅しています。これらの文書は、IT担当者がソフトウェア・アプリケーションの監視やトラブルシューティングを行う際に参照できる、単一の真実の情報源（SSOT）を形成します。

ソフトウェアと製品に関するドキュメント：アップデート頻度

ソフトウェアドキュメントは、新しいコミットがメインリリースチャンネルにマージされると、常に更新されなければなりません。ソフトウェア・ドキュメントは、新しい機能やコマンドを強調し、古い機能を非推奨とする必要があります。また、新しい依存関係や変更された依存関係を文書化し、すべてのターゲットプラットフォームにおける機能のサポートを明確にする必要があります（ある機能はWindowsで動作するが、Linuxでは動作しないなど）。

製品ドキュメントを更新する必要があるのは、基本的なソフトウェアの編集によって、ワークフローや使い勝手が変化したときだけです。開発者が決済ゲートウェイのコードを変更しても、ユーザーの決済プロセスは変わらないので、更新の必要はない。

これは、ソフトウェア製品ドキュメントの自然な階層を示すものです。技術的なソフトウェア文書が基礎を形成し、その上に後続の製品文書がある。したがって、優れたソフトウェア文書を作ることが、より優れた製品文書を作ることにつながるので、そのことに焦点を当てるべきである。

製品・ソフトウェアドキュメントのフォーマット例

製品のドキュメントは、このような枠組みで作成することができます：

• 製品名＊＊＊。

• 製品目的の概要*。

• セットアップガイド

• カスタマーサポートリンク※1

同様に、ソフトウェアのドキュメントもこのフレームワークに従うことができます：

• ソフトウエア名 * *ソフトウエア名

• ソフトウエアの目的の概要*。

• ソフトウエアの依存関係

• インストールガイド

• ファンクション1の説明とイメージ ファンクション2の説明とイメージ *ファンクション3の説明とイメージ

• ファンクション2の説明と画像 * *ファンクション2の説明と画像

• テクニカルサポートリンク※1

明らかに、この2つの文書タイプは互いに密接な関係にあり、同様の構造に従っています。つまり、製品チームとソフトウェアチームは互いに学ぶべきことが多く、ドキュメントの共同作業には多くの可能性があるのです。

プロダクトチームとソフトウェアドキュメンテーションチームは互いに補完し合える

製品ドキュメントとソフトウェアドキュメントの間には、明確な類似性があります。このことから、製品チームとソフトウェアチームは一緒に仕事をすることができるのだろうかという疑問が生まれます。

そうです、できますし、そうすべきです！

ソフトウェアチームは、技術的な専門用語や基礎となる技術を理解します。製品チームは、ユーザーが何を見、何を望み、何を必要としているのか、つまりユーザーエクスペリエンスを理解します。ソフトウェアドキュメントのライターは、詳細な技術情報を提供し、製品ドキュメントのライターは、素人の読者が消費できるように技術的な詳細を希釈することができます。

一般人が理解できるような高度な知識を持たずに、一般人の言葉で何かを説明しようとすることを想像してください。これは、ソフトウェアのドキュメントよりも製品のドキュメントが先に作られた場合に起こることです。

量子力学って何？シュレディンガーの猫」が、あなたの頭の中に最初に思い浮かぶことでしょう！でも、量子力学と猫に何の関係があるのでしょうか？ユーザーにとっては、どうでもいいことです。物理学者にとっては、それがすべてを意味するのです。

Start With Software Documentation, End With Better Product Documentation in Docsie

結論として、ソフトウェア文書をその後の製品文書のテンプレートとして使用する場合、多くの利点があります。ソフトウェア・ドキュメントは、IT担当者と製品ドキュメント作成者のための単一の真実のソースとして機能する必要があります。それが書かれた後、製品ドキュメントライターは、校正と品質保証のための技術的なガイダンスとともに、ユーザーフレンドリーな知識を簡素化して顧客と共有するための明確さと理解を得ることができます。

つまり、優れたソフトウェア文書から始めることで、ライターはより優れた製品文書を作成することができるのです！

Docsieを使えば、お客様の業務に役立つドキュメントを作成することができます。スタートアッププラン ](https://www.docsie.io/pricing/)(forever free!) にご登録いただき、Docsieで楽しいドキュメントをお届けしてください！