6つのベストソフトウェアドキュメントの例とベストプラクティス

良好で繁栄するソフトウェア製品の背後にある成功を知りたいですか？

それは彼らの文書です。

優秀な企業は、ソフトウェアのドキュメントに多くを投資しています。実際、彼らが最初に行うことは、ソフトウェアの目的、範囲、その動作、業界の参照を含むドキュメントを作成することです。

これにより、利害関係者は、ソフトウェア開発コスト、タイムライン、マーケティングの角度と戦略、機能のギャップ、重要な機能を覗き込むことができます。

開発に役立つだけでなく、ソフトウェアドキュメントは、新しい従業員のトレーニング、新しい顧客の採用、サポートの提供に最も一般的に使用される方法の1つです。

また、複数のソフトウェアとそのドキュメントを作成しました。その後、ソフトウェアドキュメントでガイドできます。

それでは、始めましょう！

私たちは、ヘロセムを通じて推奨するすべての製品を厳密にテストおよび調査します。レビュープロセス。また、リンクを通じて購入すると、手数料を獲得する場合があります。

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

ソフトウェアのドキュメントは、ソフトウェアの開発を支援し、開発プロセスと進捗を記録し、ソフトウェアアプリケーションの仕組みを説明し、ユーザーを使用してソフトウェアを効果的にガイドし、カスタマーサポート資料として機能する任意の書面またはビデオ資料です。

ソフトウェアドキュメントの種類

ソフトウェアプロジェクトは、完了するまでに数日から数年かかる場合があります。したがって、あらゆるビジネスソフトウェアを開始する前に、あなたが何をしているのかを理解することが重要です。

その結果、ソフトウェアのドキュメントは、膨大な範囲のドキュメントをカバーしています。計画段階から法律の遵守まで。

ソフトウェア開発ライフサイクル、ソース-CDS.CERN.CHで作成されたドキュメントの一部

これは、ソフトウェアのドキュメントとその中でカバーするものを開始する方法についての一般的なアイデアを得るのに役立ちます。

1。プロジェクトのドキュメント

プロジェクトのドキュメントは、ソフトウェア作成の初期段階で作成され、ライフサイクル全体で維持されます。

ソフトウェア開発プロセスに関する鳥の目の見解を示すため、意思決定に大いに役立ちます。

研究、テスト、アイデア、例、リソースの割り当て、会議の詳細、作業の進捗、マイルストーン、将来の目標をカバーしています。

2。要件と設計文書

要件と設計のドキュメントはどちらも手から手から取ります。実際にコーディングを開始する前に、ソフトウェアの大まかなスケッチを作成するようなものです。

次のような重要なコンポーネントが含まれています。

• システムの概要
• 高レベルの目標と目標
• 機能要件
• 受け入れ基準
• システムアーキテクチャ
• テクノロジースタック

要件ドキュメントでは、システムがすべきことに焦点を当てていますが、設計ドキュメントはシステムの構築方法に焦点を当てています。

ベストプラクティス：ソフトウェアからすべての要件をリストし、それらをいくつかの段階に分割するのが最善です。これは、最初からより良いソフトウェアを設計するのに役立ちます。

そもそも適切に設計されていないという理由だけで、多くのソフトウェアが再設計されています（例えば、別の言語で書き換えられたり、再構築されたりします）。

3。技術文書

技術文書は、ソフトウェアシステムがどのように構築、運用、維持されるかをカバーしています。

ソフトウェアのドキュメントでは、説明するために技術文書を作成する必要があります。

• コードの仕組み
• API（アプリケーションプログラミングインターフェイス）
• データベーススキーマ（表、関係、データフロー）
• ソフトウェアの依存関係をアップグレードする方法
• ガイドのトラブルシューティング

テクニカルドキュメントを作成して作成するための完全なガイドがあります。チェックしてください！

4。ユーザーのドキュメント

ユーザーのドキュメントは、エンドユーザー（顧客）がソフトウェアを効果的に使用するのに役立ちます。

それは以下を含みます：

• ユーザーマニュアル：エンドユーザー向けに作成。たとえば、ユーザーが製品の特定の機能を使用する方法。
• トレーニング資料：エンドユーザー向けのさまざまなトレーニングリソースが含まれています。たとえば、セットアップガイド、ビデオ、またはコース。

ユーザーのドキュメントは、技術的なドキュメントとは少し異なります。それについて詳しく知るのに役立つガイドがいくつかあります。

• 5つの最高のユーザードキュメントの例（Good＆Bad + Tips）
• ユーザーマニュアルの作成方法：ゼロからヒーローまで（フルガイド）

5。ドキュメントのテスト

QA（品質保証）チーム向けに特別に作成されたドキュメントまたはガイドラインのテスト。ソフトウェアの品質が市場の基準を満たしたり、利害関係者の要求を満たしていることを確認します。

それは以下を含みます：

• テスト計画とテストケース
• ソフトウェア機能のテスト中にフォローするチェックリスト
• コード品質ガイドライン
• 自動テスト

6。メンテナンス /セキュリティドキュメント

このタイプのドキュメントは、開発者とチームがソフトウェアを維持、更新、デバッグ、トラブルシューティングするのに役立ちます。

それは以下を含みます：

• ガイドライン、またはチェックリストを更新します
• ソフトウェアの依存関係を更新するガイド
• アクセスコントロール
• インシデント計画
• ノートをリリースします

7。法律およびコンプライアンスのドキュメント

ソフトウェアが法的、規制、業界の基準に従うようにするための法的およびコンプライアンスの文書。

次のような法的文書：

• エンドユーザーライセンス契約（EULA）
• 利用規約（TOS）
• プライバシーポリシー
• ソフトウェアライセンスと使用情報

次のようなコンプライアンスドキュメント：

• GDPR、CCPA、HIPAAなどの規制を含むデータ保護とプライバシーコンプライアンス。
• セキュリティコンプライアンス
• アクセシビリティコンプライアンス
• 業界固有の規制

探索：ソフトウェアのドキュメントとは何ですか？

6つのベストソフトウェアドキュメントの例から学ぶ必要があります

1。WordPress

以前にWordPressをすでに使用していた可能性が高いので、これは学習するのに最適なソフトウェアドキュメントの例かもしれません。

WordPressは、Web上のすべてのWebサイトの43％で使用されます。したがって、その文書は、世界中の何百万人もの人々にサービスを提供するために最高のものの1つでなければなりません。

これには、開発者、デザイナー、ブロガー、作家、またはウェブサイトを構築したい人が含まれます。

WordPressメインドキュメントは、3つの異なるセクションに分かれています。

1. WordPressを学ぶ：詳細なコース、ビデオ、書かれたチュートリアルの形でガイドを含めます。初心者、中級および上級ユーザーを対象としています。
2. 主なドキュメント：通常のユーザーを対象としています。 WordPressの機能の概要を提供するには、短い簡単な書面によるチュートリアルの形式です。
3. 開発者リソース：WordPressのテーマ、プラグインを作成する、またはカスタムコーディングでWordPressを拡張する開発者を対象としています。開始ガイド、APIドキュメント、コーディングの例が含まれます。

全体として、それはウェブサイトを作成したい、またはWordPressを始めたい人に最適なリソースハブを作成します。ナビゲートしたり、フレンドリーで詳細を検索したり、例でいっぱいで、非常に便利です。

WordPressソフトウェアのドキュメントから学ぶこと：

• 彼らは視聴者を知っています。その結果、ユーザーの知識レベルや専門知識に基づいて作成された複数のドキュメントセクションとガイドを見ることができます。
• 継続的な更新。ソフトウェアのドキュメントは、一度限りのものではなく、ソフトウェア機能、UI、または機能が時間とともに変化する場合があります。同じことがWordPress（古典的なテーマからブロックテーマやグーテンバーグの追加）で起こり、更新ごとにドキュメントを更新するようにしました。
• サポートフォーラム。事前のチュートリアルとガイド以外に、WordPressには、各プラグインのサポートフォーラムとテーマも含まれています。これは、ユーザーが自分で問題を解決するのに苦労している場合に非常に役立ちます。
• SEO（検索エンジンフレンドリー） 。 WordPressユーザーとしての9年以上のキャリアでは、WordPressのドキュメントを直接訪問または閲覧することはめったにありませんでした。私がしたのはGoogleで検索することだけで、クエリの解決策を見つけました。 WordPressドキュメントとユーザー生成サポートページは、Google（または他の検索エンジン）で簡単にインデックスを作成し、簡単に見つけることができます。
• FAQ 。ほとんどの場合、FAQはドキュメントで見逃されます。しかし、WordPressはそれらを見逃しませんでした。 FAQはインスタント情報またはソリューションを提供し、スキャンしやすいです。
• フィードバックシステム。各ガイドに関するフィードバックを提供できます。これは、時代遅れで役に立たないガイドを見つけるための役立つ機能です。

WordPressのドキュメントについて気に入らないこと：

• 多言語のドキュメントはありません。ただし、言語でサードパーティのWordPressガイドを簡単に見つけることができます。しかし、WordPressが一般的な言語のチュートリアルを作成したことを願っています。

2。ヘロセムの知識ベース

私たち自身のソフトウェアドキュメント。

それはそこにある最良の例ではありませんが、あなたのほとんどが私たちと同様の状況を持っていることを考えると、

• どこから始めればいいのかわからない
• 低予算

それは学ぶべき良い例かもしれません。

Hearothemesは、ユーザーが公開および内部で使用するために、コーディングの知識なしに知識ベースまたはドキュメントWebサイトを作成できるようにするHeroic Knowledge Baseを含むカスタマーサポートプラグインを提供します。

Herothemesのドキュメントの例から学ぶことの例：

• 必要なドキュメントのみを作成し、改善します。ターゲットを絞った顧客のほとんどが中級レベル（開発者、WordPressユーザー）であり、ソフトウェアは非常に簡単で使いやすいことを考えると、ヘロセムにはガイドがほとんどありません。
• 目次（TOC） 。これらのガイドには完全なウォークスルーが含まれていることを考えると、TOCは必要な情報を見つけるのに役立ちます。
• スクリーンショット。私たちのほとんどは、最初からドキュメントの良い予算をspareしまない（特にデザイナーを高品質のビジュアルを作成するために割り当てる）ことができないため、スクリーンショットを追加することは何も追加よりもはるかに優れています。しかし、デザイナーによって作成されたビジュアルは、本当にプレミアムな感触を与えます。
• チケット追跡をサポートするドキュメント。

これは、ドキュメントから生まれたサポートチケットを追跡するための英雄的なKB分析機能の1つです。役に立たない、時代遅れのコンテンツを見つけるのに非常に役立ちます。

• FAQ 。ユーザーは、払い戻しポリシーや将来のアップグレードなど、よく尋ねられる多くの質問をします。ドキュメントを介して回答すると、ユーザーが検索バーとAIヘルプアシスタントで簡単に見つけることができます。
• AIヘルプアシスタント。検索バーと同様に、AIヘルプアシスタントは、ユーザーがクエリに対する回答を簡単に見つけるのに役立ちます。ドキュメントのコンテンツでトレーニングされているため、回答は関連性が高く役立ちます。

Herothemesドキュメントについて気に入らないこと：

Herothemesは複数のソフトウェアソリューションを提供しているため、ドキュメントコンテンツのグループ化は少し混乱しています。

WordPressを使用してドキュメントWebサイトを作成するのに役立つガイドがいくつかあります。

• WordPressの知識ベースの作成方法（ステップバイステップガイド）
• 内部ドキュメントを作成する方法

3。BARN2ソフトウェアポートフォリオドキュメント

Barn2は、90,000を超えるWebサイトで使用されるWordPressとWooCommerceに基づいて複数のソフトウェア製品を販売しています。

単一のポータルから複数のソフトウェアドキュメントを提供することは困難ですが、Barn2は美しくそれを行います。

複数の製品がある場合は、Barn2の例を絶対に調べる必要があります。

BARN2ドキュメントの例から学ぶことの例：

Barn2は、サポートページを非常に慎重に作成しました。全体的な機能と有用性で見ることができます。

サポートページにアクセスすると、特定の製品を選択するオプションを備えた著名な検索バーがあります。

事前販売、ライセンス、更新、技術的な問題に関連するよくある質問。これはやり取りするのに非常に魅力的であり、迅速な回答も提供します。

検索が結果を提供できない場合、それは人間のサポートに到達する方法を示しています。

主なソフトウェアのドキュメントについて話す：

• 上部のすべての重要なガイドが見つかり、ガイドは簡単なナビゲーションのために異なるセクションに分かれています。
• 筆記およびビデオのチュートリアルが含まれています。
• 人間のサポートは、サイドバーCTAで簡単にアクセスできます。
• スキャン機能を向上させるために、メモ、ヒント、警告メッセージ、およびコードスニペットのカスタムブロック/デザイン。

Barn2のドキュメントについて気に入らないこと：

• フィードバックシステムなし。彼らは人間のサポートへの直接アクセスを提供しますが、ユーザーからリアルタイムのフィードバックを収集する方法はありません。時代遅れの情報とチュートリアルにつながる可能性があります。

Barn2はまた、英雄的な知識ベースを使用してソフトウェアドキュメントを作成します。

4。iPhoneユーザーガイド

iPhoneのユーザードキュメント（iOSソフトウェアガイド）については、好きで嫌いなことがたくさんあります。

これは、Followの簡単な手順を備えた派手なソフトウェアドキュメントであり、Appleに期待できるようなものです。

iPhoneのドキュメントの例から学ぶべきこと：

iPhonesドキュメントは見事に見えます。

• 単一の列レイアウト
• たくさんの空白
• 小さな段落とコンテンツ
• 美しいビジュアル
• 見出し、リスト、および仕切りの適切な使用

彼らのドキュメントのほとんどの焦点は、このような視覚的に素晴らしいガイドを作成することです。

関連するガイドを見つけたら、それをスキャンして何をすべきかを理解するのに1分もかかりません。

iPhoneのドキュメントはこのように特別に作成されているため、誰もが簡単に理解できます。

製品ソフトウェアのドキュメントを作成したい場合は、ドキュメントの予算がある場合は、iPhoneに似たユーザーガイドを作成することを強くお勧めします。

ドキュメントを美化する以外に、AppleはSEOを適切に使用することを忘れませんでした。具体的には：

• タイトルと見出し構造
• TOC、関連する投稿、以前および次のナビゲーションの形での相互リンク

ガイドフィードバックシステムは素晴らしいです。 [はい]または「いいえ」をクリックし、必要に応じてフィードバックも提供します。

フィードバックシステムはそれほどクールに聞こえませんが、何百万人ものユーザーがフィードバックを提供している場合、単純なイエスまたはノーノートラッキングはガイドのパフォーマンスを確認するのに本当に役立ちます（そのフィードバックをすべて読めないだけですか？） 。

Appleは、ソフトウェアバージョン（この場合はiOSバージョン）に基づいたガイドも提供しています。

iPhoneのドキュメントについて気に入らないこと：

上記のiPhoneのドキュメントについて多くのことを称賛しましたが、迷惑なものもいくつかあります。

特にナビゲーション部分。

• すべてのガイドリンクが含まれているため、目次は役に立ちません。
• 検索アイコンが小さすぎて気付くには小さすぎます。

5。ソフトウェアデザインドキュメント（内部例）

ソフトウェアのドキュメントは、ソフトウェアを作成するというアイデアから始まります。

たとえば、最初のソフトウェアドキュメントには以下が含まれます。

• ソフトウェアのニーズは何ですか
• 範囲
• それがどのように機能するか
• 参照

詳細情報を入手すると、将来の多くの会議を回避し、新しい従業員を訓練し、具体的なガイドラインを作成します。

ロードトリップアドバイザーソフトウェアデザインドキュメントから多くのことを学ぶことができます。

ソフトウェアの構築（この場合はWebアプリケーション）を開始するか、新しい従業員がソフトウェアからの要件を理解できるようにするために必要なすべての要件の概要を説明します。

さらに、ソフトウェア開発中はいつでも改善できます。

この例から学ぶべきこと：

• 具体的なガイドラインを作成する目的、範囲、定義などの基本的で重要な情報が含まれます。
• 開発者が要件をよりよく理解できるように、図と視覚的なグラフィックを使用します。例：図を使用した機能の接続またはフローを説明します。

6. Googleドキュメント

誰がGoogleを知らないのですか？ Chrome、Gmail、Google Maps、Googleドライブ、YouTubeなど、毎日最高のソフトウェアを使用しています。

コンピュータデバイスとモバイルデバイスの両方で利用できます。異なるOS、デバイス、解像度、設定。

このような状況では、混乱せずに何か良いものを作成することは悪夢でなければなりません。そして、 Googleは彼らのドキュメントで本当に良い仕事をしています。

Googleのソフトウェアドキュメントから学ぶべきこと：

• コンテンツクラスターを簡素化するためのタブとアコーディオンの優れた使用。

複数のデバイス用のソフトウェアを作成する場合、これは複数のドキュメントの作成を避ける方法です。

• 素晴らしいフィードバックシステム。上記の例のいくつかと同様に、Googleには、ユーザーからのフィードバックも収集するYES/NOフィードバックシステムも含まれています。

しかし、Googleはここでさらに一歩進んでいます。特定のセクションに基づいてフィードバックを収集するシステムがあります。これは非常に直感的で便利です。

• クイックコンテンツ。そこに移動し、これをクリックして、ダウンロード、インストール、ブームを作成します。これは、Googleドキュメントのチュートリアルがどれだけ迅速に感じるかです。
• 検索、ヘルプセンター、コミュニティ、製品のページをすばやくアクセスするためのトップバー。
• 複数の言語で利用可能なドキュメント。

Googleのドキュメントについて気に入らないこと：

ここで不平を言うためにたくさんのことを見つけようとしましたが、最終的にはできませんでした。 Googleには確かに優れたソフトウェアドキュメントがあります。

最終的な考え

このソフトウェアドキュメントの例ガイドでは、多くのさまざまな例について説明し、個人的な経験も共有しています。

ここにいくつかの最後の言葉があります：

1. ソフトウェアの作成から始めたら、ソフトウェアの目的、範囲、機能、リリース基準を概説する内部ガイドを作成します。
2. ソフトウェアを開発するときにドキュメントポートフォリオを構築します。たとえば、APIドキュメント、および技術ドキュメント。
3. ソフトウェアを起動する前に、セットアップガイド、ユースケース、機能の概要、よくある質問を含むユーザードキュメントを作成します。
4. 起動後、最も一般的なユーザーの問題に対処し、古いドキュメントを改善するためのチュートリアルを作成します。

ドキュメントは冗談ではありません。恐ろしいソフトウェアの再開発や再設計プロセスから救うことができます。私はあなたがより良い顧客体験を提供し、顧客を維持するのを手伝うことができます。

ソフトウェアドキュメントソリューションを探している場合、 Heroic Knowledge Baseには、このガイドで説明したすべてのものが提供されます。

試してみてください！