ソフトウェアドキュメントとは何ですか? 開始するためのタイプとベストプラクティス

開発者とエンドユーザーがソフトウェアからできる限り多くの価値を得られるようにしたい場合は、高品質のソフトウェア ドキュメントを作成する必要があります。

しかし、ソフトウェア ドキュメントとは実際何でしょうか。プロジェクト用にドキュメントを作成するにはどうすればよいでしょうか?

この投稿では、次のようなソフトウェア ドキュメントについて知っておく必要があるすべてのことを詳しく説明します。

• ソフトウェアドキュメントとは何ですか?
• さまざまな種類のソフトウェア ドキュメント (例付き)
• ソフトウェアドキュメントを公開する方法 (最良のツール)
• 高品質のソフトウェアドキュメントを作成するためのベストプラクティス

掘り下げてみましょう！

ソフトウェアドキュメントとは何ですか?

ソフトウェア ドキュメントは、エンドユーザー、開発者、従業員がソフトウェアを理解し、それを使用して目的を効果的に達成するのに役立つコンテンツです。

通常、ソフトウェアのドキュメントは Web サイトで公開します。 人々はそれにアクセスして、ソフトウェアとその仕組みについて詳しく知ることができます。

ソフトウェア ドキュメントの広義の定義には、さまざまな種類のソフトウェア ドキュメントがあります。 次にそれについて議論しましょう。

さまざまな種類のソフトウェア ドキュメント

さまざまな種類のソフトウェア ドキュメントは、いくつかの広いカテゴリに大まかに分類できます。

最初に考慮すべきことは、ドキュメントがどのようなタイプの人を対象としているかです。

• ユーザー ドキュメント– これは、製品のエンド ユーザー向けに作成したドキュメントです。 これは、特別な技術的知識を持っているかどうかに関係なく、通常のユーザーの観点からソフトウェアの使用方法を理解するのに役立ちます。
• 開発者ドキュメント– これは、API ドキュメントなど、開発者向けに作成されたより技術的なソフトウェア ドキュメントです。

2 番目の考慮事項は、ドキュメントが社外向けか社内向けのどちらを対象としているかです。

• 外部ソフトウェア ドキュメント– これは、ユーザーを支援するために作成した公開ドキュメントです。
• 内部ソフトウェア ドキュメント– これは、従業員がより効率的に作業し、重要な詳細を理解できるようにするために作成した非公開のドキュメントです。

たとえば、ソフトウェアの作業を支援する内部チーム用の開発者ドキュメント セットと、外部開発者用の公開開発者ドキュメント セットを別のセットとして持つとします。

この種のソフトウェア ドキュメントをもう少し詳しく見てみましょう。

開発者向けドキュメントのソフトウェア ドキュメントの例

• API ドキュメント– ソフトウェアの API を操作する方法を開発者に示します。
• Readme – ソフトウェアの紹介とその機能の説明 – 通常、人々が最初に読むものです。
• リリース ノート– 重要な変更を含め、ソフトウェアの新しいリリースを文書化します。
• アーキテクチャ ドキュメント– ソフトウェアの構造を示します。図も含まれる場合があります。
• データ モデルのドキュメント– さまざまなデータ構造間の関係を含め、ソフトウェア内のさまざまなデータ構造を文書化します。
• プロセスの文書化– バグレポート、ロードマップ、品質保証、テストプロトコルなどの主要なプロセスを文書化します。

開発者に焦点を当てた実際のソフトウェア ドキュメントの例については、次のようなさまざまなトピックをカバーする Gravity Forms の「開発者」ドキュメントを参照してください。

• PHP フック (WordPress 用)
• データオブジェクト
• PHP API
• データベース
• REST API

たとえば、REST API ドキュメントは次のようになります。

ユーザードキュメントのソフトウェアドキュメントの例

• スタート ガイド- ソフトウェアをすぐに起動して実行する方法をユーザーに示します。
• 特定のユースケースのチュートリアル– 特定のタスクを実行するためのより具体的なチュートリアル。
• 用語集/リファレンス マニュアル– ユーザーが重要な用語と詳細を理解するのに役立ちます。
• FAQ – よくある質問に答えます。

よりユーザーに焦点を当てたソフトウェア ドキュメントがどのようなものであるかを示す実際の例については、上記と同じ Gravity Forms の例を参照してください。

Gravity Forms のよりユーザーに焦点を当てた記事を見ると、ソフトウェア インターフェイスを使用してタスクを実行する方法に関するステップバイステップのチュートリアルが数多く掲載されており、用語集や主要な機能の説明も含まれています。

開発者向けソフトウェアのドキュメントと比較すると、より多くのスクリーンショットと平易な説明が表示され、コード ブロックは大幅に少なくなります。

ソフトウェア ドキュメントを公開する方法: 3 つの最高のソフトウェア ドキュメント ツール

ソフトウェア ドキュメントを Web サイトで公開するには、専用のソフトウェア ドキュメント ツールまたは何らかの種類のナレッジ マネジメント システムが必要になります。

このセクションでは、最高のソフトウェア ドキュメント ツールのいくつかを簡単に説明します。 次に、次のセクションでは、高品質のドキュメントを作成するためのベスト プラクティスをいくつか説明します。

ここでさらに詳しく知りたい場合は、最高のドキュメント ツールと最高の技術ドキュメント ソフトウェアに関する完全なガイドをお読みください。

英雄的な知識ベース

Heroic Knowledge Base は、人気のあるオープンソース WordPress ソフトウェアのドキュメントおよびナレッジ ベース プラグインです。

Heroic Knowledge Base を使用すると、ドキュメントを自己ホストして完全な制御を維持しながら、効果的なソフトウェア ドキュメントの作成に必要なすべての機能にアクセスできます。

Heroic Knowledge Base で得られる主要な機能の一部を次に示します。

• 吹き出しやその他の重要なスタイルの詳細用の組み込みブロックを含む、柔軟なコンテンツ エディター。
• 自動目次。ユーザーはドキュメント記事で取り上げられている内容をすぐに確認し、特定のセクションにジャンプできます。
• ネイティブ WordPress リビジョン システムによるリビジョン管理とバージョン履歴。
• ライブ提案、カテゴリなどを備えたリアルタイム Ajax 検索を含むコンテンツ検出機能。
• ユーザーが記事を役立つか役に立たないか評価し、フィードバックを共有できるユーザー フィードバック システム。
• 検索分析を使用すると、ユーザーが何を検索しているか、結果がゼロの検索語を確認できます。
• ユーザーがサイト上のどこからでもソフトウェア ドキュメントを検索してアクセスできるようにするインスタント アンサー ウィジェット。

Heroic Knowledge Base と WordPress は両方とも自己ホスト型でオープンソースであるため、必要に応じて設定を自由に変更することもできます。

パスワード、ユーザー アカウント、IP アドレス、イントラネットなどのさまざまな方法を使用して、ドキュメントを公開したり、ドキュメントへのアクセスを制限したりできます。

Heroic Knowledge Base は年間わずか 149 ドルからご利用いただけます。

ドキュメントを読む

Read the Docs は、開発者向けドキュメントの作成を支援することに重点を置いたドキュメント ツールです。

開発者向けの技術ドキュメントの作成に特に重点を置いている場合は、これも検討すべき良い選択肢になる可能性があります。

Git を使用してコンテンツとリビジョン履歴を管理し、ドキュメントをフロントエンド インターフェイスにデプロイできます。

Read the Docs のその他の注目すべき機能をいくつか紹介します。

• ユーザーが何を読んだり検索したりしているかを確認するための組み込みの分析。
• 複数の同時ビルドをサポートします。これは、ソフトウェアの複数のバージョンを提供する場合に役立ちます。たとえば、バージョン 1.0 用のドキュメント セットとバージョン 2.0 用のドキュメント セットなどです。
• PDF、HTML、epub などのさまざまな形式でドキュメントをエクスポートします。
• ユーザーがドキュメントを見つけやすくするためのライブ検索の提案。

オープンソース ソフトウェア プロジェクトをお持ちの場合は、Read the Docs を無料で使用できます。

商用ソフトウェア製品の場合は、月額 50 ドルから始まる有料の Read the Docs for Business サービスがあります。

GitBook

GitBook は、Git を使用してドキュメントを管理できるもう 1 つの技術ソフトウェア ドキュメント ツールで、GitHub と GitLab の両方のリポジトリをサポートします。

また、Git を使用したくない場合は、GitBook を使用してテキスト エディタを使用してドキュメントを作成したり、マークダウン ファイルや .doc ファイルからドキュメントをインポートしたりすることもできます。

GitBook が提供するその他の注目すべき機能をいくつか紹介します。

• リビジョンとバージョン履歴を追跡するバージョン管理。
• ライブ チーム編集は、複数の著者が記事で共同作業する必要がある場合に役立ちます。
• 「スペース」と「コレクション」を使用して記事を整理します。各スペースには複数のコレクションを含めることができます。
• PDF エクスポートオプションにより、ユーザーはドキュメントを PDF ダウンロードとして簡単にエクスポートできます。

GitBook は、非営利プロジェクトまたはオープンソース プロジェクトには無料です。

商用ソフトウェア プロジェクトの場合、GitBook はユーザー 1 人あたり月額 8 ドルから始まり、最小ユーザー数は 5 人です。 つまり、最も安い月額料金は月額 40 ドルです。

ソフトウェアドキュメント作成のベストプラクティス

最後に、効果的なドキュメントを作成するために役立つソフトウェア ドキュメントのベスト プラクティスをいくつか掘り下げてみましょう。

ユーザーの目標とニーズについて考える

ソフトウェア ドキュメントの記事を作成するときは、次のような基本的な質問に答えることから始めることが重要です。

• あなたが書いているユーザーは誰ですか?
• ユーザーは何を達成しようとしているのでしょうか?
• ユーザーはどのレベルの技術知識を持っていますか?

これらの質問に対する答えが分かれば、どのようなコンテンツを取り上げるべきか、そして記事を最適な方法で構成する方法を理解するのに役立ちます。

たとえば、ソーシャル メディア スケジュール ソフトウェアを提供しており、ソーシャル メディア マネージャーが最初のソーシャル メディア投稿をスケジュールするのに役立つ記事を書いているとします。

ソフトウェアのドキュメントを作成するときは、一般のエンド ユーザーがその目標を達成するための最も簡単な方法を示すことに重点を置きたいと思うでしょう。

開発者が独自の統合を設定できるようにするための API も提供している場合は、それを別の記事で取り上げる必要があるでしょう (ただし、そのメソッドについて言及し、リンクすることもできます)。

開発プロセスにソフトウェアドキュメントを含める

ソフトウェアのドキュメントを作成しているとき、プロジェクトが完了するまでドキュメントを作成しないという罠に陥りがちです。

ただし、新機能や変更が文書化される前に出荷される可能性があるため、これによりすぐに文書化の負債が発生する可能性があります。

これを回避するには、ソフトウェアのドキュメントをソフトウェア開発サイクルの一部として意識的に組み込みます。 新しい機能や製品がまだ文書化されていない場合は、コード自体が完成していても、出荷する準備ができていません。

ドキュメントをソフトウェア開発プロセスの中核要件とすることで、出荷するすべてのものに適切なドキュメントを確実に添付することができます。

一貫した書式設定とスタイルを使用する

人々がソフトウェア ドキュメントをより効果的に操作できるようにするには、すべてのドキュメントで一貫した書式とスタイルを使用することが重要です。

同じ書式を使用すると、読者はソフトウェア ドキュメントがどのように構成されているかを知ることができ、必要な情報にすばやくアクセスしやすくなります。

この一貫性を実現するには、専用のソフトウェア ドキュメント スタイル ガイドを作成するとよいでしょう。

ソフトウェア ドキュメント管理ツールには、一貫したスタイルを実現するための機能が含まれている場合もあります。

たとえば、Heroic Knowledge Base プラグインには、重要な情報や警告を強調表示する事前にスタイル設定されたコールアウトが含まれています。 これらを使用すると、すべてのドキュメントにわたって一貫した書式設定を保証できます。

専門家を利用して技術文書を作成する

ユーザー向けのソフトウェア ドキュメントの場合、内容を作成する主題の専門家は必要ない場合があります。

ただし、開発者向けの API ドキュメントなど、より技術的なソフトウェア ドキュメントの場合は、関連する技術的知識を持つ人にそれらのドキュメントを作成するよう割り当てる必要があるでしょう。

組織にそのポジションのために雇用するリソースがある場合、これはドメインの専門知識を持つ専任のテクニカル ライターになる可能性があります。 あるいは、開発者の一人である可能性もあります。

重要なことは、作成者がソフトウェアの技術的側面を他の技術ユーザーに説明できるほど深いレベルで理解していることです。

人々がコンテンツを見つけやすくする (検索/フィルター)

ドキュメントのライブラリが増大するにつれて、ユーザーが自分のニーズに対応したドキュメント記事を見つけることがより困難になります。

この問題を回避するには、ソフトウェア ドキュメントの見つけやすさを向上させることに重点を置く必要があります。

最初の戦略の 1 つは、ドキュメントを種類ごとに分けることです。

たとえば、通常は、エンドユーザーのドキュメントを開発者ソフトウェアのドキュメントから分離する必要があります。

その中で、カテゴリを使用して記事をさらに分割することもできます。 機能、ユースケース、アドオンなど、ソフトウェア製品にとって論理的に意味のあるものに基づいてカテゴリを使用できます。

上記と同じ Gravity Forms の例に合わせて、Gravity Forms がエンドユーザー ドキュメントを機能タイプごとに分割していることがわかります。

もう 1 つの便利な発見機能は、ライブ検索の提案です。 ユーザーは検索ボックスに関連するクエリを入力し始めると、そのクエリに一致するドキュメント記事を即座に表示できます。

Heroic Knowledge Base などの多くのドキュメント ツールには、ライブ検索機能が組み込まれています。

ソフトウェアのドキュメントを常に最新の状態に保つ

ソフトウェアは常に変更されているため、ソフトウェアのドキュメントは常に進行中です。

ソフトウェアの変更に応じて、その変更を反映するためにドキュメントを速やかに更新する必要があります。

そうしないと、ドキュメントが「役に立たない」だけでなく、実際にユーザーに混乱を引き起こす可能性があります。

これらの更新を確実に行うには、ドキュメントと更新プロセスの所有者として特定の人を割り当てる必要があります。 そうすれば、すべてを正確に保つ責任が誰にあるのかが曖昧になりません。

顧客のフィードバックを活用してドキュメントを改善する

独自のチームがソフトウェア ドキュメントのレビューと更新に取り組むことに加えて、顧客からのフィードバックも考慮する必要があります。

顧客は、特定のソフトウェア ドキュメントの記事がどれほど役立つ (または役に立たない可能性がある) かどうかに関する貴重な情報と、それを改善する方法に関する詳細を提供できます。

顧客フィードバック プロセスを自動化するには、顧客フィードバック用の機能が組み込まれたドキュメント管理ツールを探す必要があります。

たとえば、Heroic Knowledge Base プラグインを使用すると、ユーザーは記事を役立つか役に立たないか評価したり、オプションで自由形式のフィードバックを提供したりできます。

その後、ダッシュボードからこのすべての情報を表示して、改善が必要なドキュメント記事をすぐに見つけることができます。

今すぐソフトウェアの文書化を始めましょう

ソフトウェアのドキュメントは、あなたとあなたの顧客がより効率的に作業し、ソフトウェアからより多くの価値を引き出すのに役立ちます。

ソフトウェア ドキュメントにはさまざまな種類があるため、どの種類がソフトウェア プロジェクトのニーズに一致するかを検討する必要があります。

内部チームまたは外部チーム、さらには開発者とエンド ユーザーなど、さまざまなタイプの顧客に応じて、異なるドキュメントが存在する場合があります。

効果的なドキュメントを作成するには、この投稿のベスト プラクティスに従ってください。

そのドキュメントを公開するには、強力な WordPress ソフトウェアをベースにした Heroic Knowledge Base などのオープンソース ツールを使用できます。

高品質のソフトウェア ドキュメントを公開するために必要な機能をすべて備えた、自己ホスト型プラットフォームの柔軟性と所有権が得られます。

さらに詳しく知りたい場合は、ここをクリックして Heroic Knowledge Base にアクセスしてください。