プロダクトチームとソフトウェアチームの共通の悩み：ドキュメント作成¶
プロダクトチームもソフトウェアチームも、共通の悩みを抱えています：ドキュメント作成です。
プロダクトドキュメントとは、ユーザー向けのマニュアルやガイドのことで、製品のワークフローとユーザーインターフェースを説明するものです。一般ユーザーがこの製品を使いこなすにはどうすればよいのか？この意味では、プロダクトドキュメントはソフトウェア製品にも適用できます。
ソフトウェアドキュメントは、ソフトウェア製品の基盤技術、前提条件、設定可能な属性について説明します。IT管理者はどのようにソフトウェア製品を設定、監視、ホスティング、デプロイするのか？このタイプのドキュメントは、特に複数のバージョンやブランチが加わる場合に重要です。
例えるなら、プロダクトドキュメントは車の運転方法を教えるようなものです。ハンドルで車を曲げ、アクセルで車を動かし、ブレーキで車を止めます。一方、ソフトウェアドキュメントは車の仕組みを教えます。ハンドルはフロントアクスルに接続されており、前輪を回転させて進行方向を変える。アクセルはエンジンへの空気流を増やし、より多くの燃料を引き込み、トルクと馬力を生み出す、といった具合です。
どちらのドキュメントも重要です。一方はユーザーを教育し、もう一方は管理者や開発者を教育します。車の運転方法を教えるのは素晴らしいことですが、車の仕組みを誰も知らなければ、車が故障したときどうなるでしょうか？
プロダクトドキュメントとソフトウェアドキュメントの微妙な違い¶
プロダクトドキュメントとソフトウェアドキュメントには、知っておくべき微妙な違いがあります：
ターゲットオーディエンスとペルソナ¶
プロダクトドキュメントは単一のオーディエンス、つまりユーザーを対象としています。ユーザーには技術的知識がないと想定し、専門用語を最小限に抑えた平易な言葉で伝えます。技術的な見習い制度と大学の学位の違いのように、理論的・概念的知識よりも実践的なやり方に重点を置いています。
ソフトウェアドキュメントはIT管理者、エンジニア、開発者を対象としています。ソフトウェアの設計とアーキテクチャ、コマンドラインでのセットアップ手順、APIと統合サポート、データ管理とレポート、ネットワークトポロジーなど、機械を動かす歯車について説明します。これらのドキュメントは、IT担当者がソフトウェアアプリケーションを監視およびトラブルシューティングする際に参照できる単一の信頼できる情報源（SSOT）を形成します。
更新頻度¶
ソフトウェアドキュメントは、新しいコミットがメインリリースチャネルにマージされるたびに一貫して更新する必要があります。ソフトウェアドキュメントは新しい機能やコマンドを強調し、古い機能を非推奨とする必要があります。新しい依存関係や変更点を文書化し、すべての対象プラットフォームでの機能サポート（WindowsではできるがLinuxではできない機能など）を明確にする必要があります。
プロダクトドキュメントは、基盤となるソフトウェアの変更がワークフローや使いやすさの変化を引き起こす場合にのみ更新が必要です。開発者が決済ゲートウェイのコードを変更しても、ユーザーの決済プロセスが同じままであれば、更新の必要はありません。
これは、ソフトウェア製品ドキュメントの自然な階層を示しています。技術的なソフトウェアドキュメントが基盤を形成し、その上にプロダクトドキュメントが構築されます。したがって、優れたプロダクトドキュメントを生み出すためには、まず優れたソフトウェアドキュメントを作成することに重点を置くべきです。
プロダクトドキュメントとソフトウェアドキュメントのフォーマット例¶
プロダクトドキュメントは、このようなフレームワークに従うことができます：
- 製品名
- 製品の目的の概要
- セットアップガイド
- 機能1の説明と画像
- 機能2の説明と画像
- カスタマーサポートリンク
同様に、ソフトウェアドキュメントは、このようなフレームワークに従うことができます：
- ソフトウェア名
- ソフトウェアの目的の概要
- ソフトウェアの依存関係
- インストールガイド
- 機能1の説明と画像
- 機能2の説明と画像
- テクニカルサポートリンク
明らかに、これら2種類のドキュメントは密接に関連しており、類似した構造に従っています。つまり、プロダクトチームとソフトウェアチームはお互いから多くを学び、ドキュメント作成で協力することで大きな可能性を秘めています。
プロダクトチームとソフトウェアチームの協力体制¶
プロダクトドキュメントとソフトウェアドキュメントには明らかな類似点があります。これは疑問を投げかけます：プロダクトチームとソフトウェアチームは協力できるのでしょうか？
はい、できますし、そうすべきです！
ソフトウェアチームは専門用語や基盤技術を理解しています。プロダクトチームはユーザーが見るもの、求めるもの、必要とするものを理解しています。つまりユーザー体験です。ソフトウェアドキュメント作成者は詳細な技術情報を提供でき、プロダクトドキュメント作成者はその技術的詳細を一般のユーザーが理解できるように噛み砕くことができます。
専門的な理解がないまま、一般の人にわかりやすく説明しようとするとどうなるか想像してみてください。それが、ソフトウェアドキュメントの前にプロダクトドキュメントを作成した場合に起こることです。
量子力学とは何でしょう？おそらく最初に思い浮かぶのはシュレーディンガーの猫でしょう！しかし、量子力学と猫に何の関係があるのでしょうか？ユーザーにとっては重要ではありませんが、物理学者にとってはすべてを意味します。
ソフトウェアドキュメントから始めて、Docsieでより良いプロダクトドキュメントを完成させる¶
結論として、ソフトウェアドキュメントをプロダクトドキュメントのテンプレートとして使用することには多くの利点があります。ソフトウェアドキュメントはIT担当者とプロダクトドキュメント作成者の信頼できる情報源として機能すべきです。その後、プロダクトドキュメント作成者は明確な理解を持って、顧客に分かりやすい知識を簡略化して共有することができます。技術的なガイダンスを校正と品質保証に活用できます。
つまり、優れたソフトウェアドキュメントから始めることで、より優れたプロダクトドキュメントを作成できるのです！
顧客の可能性を広げるドキュメントの作成を始めましょう。当社のスタートアッププラン（永久無料！）にサインアップして、Docsieでドキュメント作成の喜びを体験してください！