最初のソフトウェアドキュメントを作成するためのガイド-IT業界-php.cn

最初のソフトウェアドキュメントを作成するためのガイド

開発者として、あなたの誇りと喜びはあなたのコードです。読みやすく、乾燥した原則を満たし、ベストプラクティスを反映しており、最終製品はターゲットユーザーにとって何らかの問題を解決する優れたツールです。ただし、コードにどれだけの作業を行ったとしても、ソフトウェアにドキュメントが付属していない場合、または後付けとしてドキュメントを書いて、それをほとんど重要ではない場合、ユーザーはそれを扱うことにほとんど喜びを感じるでしょう。最終的には、別の、よりユーザーフレンドリーな製品を選択しますこの記事では、最初のソフトウェアドキュメントを書くことであなたを立ち上げて実行するための多くの実用的な指針となる原則があります。

キーテイクアウト

優れたソフトウェアドキュメントは、ユーザーの採用と理解に不可欠であり、開発者とユーザーの間のコミュニケーションツールとして機能します。チュートリアル、ハウツーガイド、リファレンスガイド、説明を含め、ソフトウェアの機能に関する包括的なガイドを提供する必要があります。

ドキュメントのターゲットオーディエンスは、使用されるコンテンツと言語が形成されるため、明確に識別する必要があります。このガイドのコンテキストでは、ユーザーマニュアルやプロジェクトのドキュメントではなく、ソフトウェアに馴染みのある開発者向けのドキュメントに焦点が当てられています。

従来のドキュメントを超えて、ブログの投稿は、ソフトウェア機能を説明し、チュートリアルを提供し、更新を共有するための便利なツールとして役立ちます。これにより、ソフトウェアを中心にコミュニティを育成し、その成長と成功に貢献できます。優れたドキュメンテーションプラクティスの例は、Greensock、React、vue.JS.
あなたのソフトウェアを参照して、マイク・ポープはあなたのソフトウェアを参照して、次のような適切なことわざを持っています。
の質問に

ドキュメントの欠如。あなたの図書館がどれほど素晴らしく、そのデザインがどれほどインテリジェントであっても、あなたがそれを理解している唯一の人なら、それは何の役にも立ちません。ドキュメントとは、API参照だけでなく、注釈付きの例や詳細なチュートリアルも意味します。ライブラリを簡単に採用できるようにするには、3つすべてが必要です。

理由を転送できます。ほぼ同じように、コードコメントは、
ではなく、の理由を説明しています。 - ドキュメントを書くための初心者向けガイド 確かに、あなたは人々にあなたのコードを使用し、最終的にそれを更新して改善することができるようにしたいです。これらはすべて、製品の背後にあるサポートコミュニティの成長に貢献している要因であり、堅牢性、成熟度、成功を得るために重要です。ソフトウェアがそれに合うように優れたドキュメントを持っていない場合、これをすべて達成するのは非常に難しいでしょう。
>

のためです

この記事は関係していない2種類のドキュメントがあります。

ユーザーマニュアル。たとえば、私の妹は自分のブログを公開するためにWordPressを使用することを決定するかもしれません。彼女は開発者ではありませんが、DEV以外がWordPressですぐにブログを稼働させて実行できると聞いています。これで、彼女はサーバー上のソフトウェアをダウンロードして構成する方法、投稿の書き込み、公開、更新方法、投稿に画像を追加する方法などの指示が必要になります。つまり、ユーザーが必要になります。マニュアル。
プロジェクトのドキュメント。この種のドキュメントは、ソフトウェア自体よりもプロジェクトに関係していますが、そのコンテンツの一部はプロジェクトのREADMEファイルに載る可能性があります。 WordPressの例を続けるために、WordPressで多くの練習をした後、ソフトウェアに機能を追加するか、バグを1つまたは2つ修正することを決めるかもしれません。この場合、Changelogs、Conventions and Best Practices、貢献ポリシー、手元のタスクに関連するチームディスカッションへの参加方法などを知る必要があります。

ここで私が念頭に置いているドキュメントの種類は、主にソフトウェアに精通していて、プロジェクトでそれを使用する必要があるレベルのレベルの開発者を対象としています。たとえば、WordPressテーマを作成している場合は、開始方法、スタイルシートとJavaScriptドキュメントを含める方法、データベースと通信する方法などを知る必要があります。

ドキュメントに何を含めるか

人気のあるアプローチは、Tom Preston-Wernerが擁護したReadme駆動型開発です。これは、コードの作成を開始する前に、ReadMeドキュメントを作成することで構成されています。このドキュメントはあなたのソフトウェアの紹介であり、通常は次のとおりです。

あなたのソフトウェアが何をしているのか、それがどのような問題を解決するかについての説明

ソフトウェアのインストール方法
私の見解では、ソフトウェア/ライブラリを使用する開発者が実際に役立つことができる強固なドキュメントを持つことは、古典的なReadMeファイルをはるかに超えているはずです。 Daniele Procidaに続いて、優れたユーザーエクスペリエンスのために、ドキュメント資料に次のアイテムを含めることをお勧めします。

初心者は、ソフトウェアドキュメントでチュートリアルを見つけるのが大好きです。チュートリアルは、ユーザーがソフトウェアを使用してプロジェクトを完了する方法を示すことで、彼らがそれでできることをすばやく理解できるようにすることです。

チュートリアルは、ある種のプロジェクトを完了するために一連の手順を通して読者を手で取る

レッスン

です。彼らは、彼らがそれで何かを達成できることを初心者に示すためにあなたのプロジェクトが必要とするものです。 -

ダニエレ・プロピダ

ハウツーガイド

ハウツーガイドは、ユーザーがソフトウェアを使用して実際のタスクを解決するのに役立ちます。 Procidaは、特定の目標に正常に到達できるように、ユーザーが提供する方向であるという意味でレシピと比較します。完全な初心者を対象としたチュートリアルとは異なり、ハウツーガイドは、ユーザーが機能、ツール、および簡単なタスクの実行方法に関する基本的な知識をすでに持っていると想定しています。

参照ガイド

参照ガイドは、ソフトウェアのコード（関数、APIなど）のテクニカル参照であり、ソフトウェアの使用方法の基本的な説明を提供します。たとえば、特定のクラスをインスタンス化する方法、特定のメソッドを呼び出す方法などのイラストがあります。

参照ガイドは、機械の技術的な説明とその操作方法です。 -

ダニエレ・プロピダ
これは、ほとんどのプロジェクトで見つける可能性が高いドキュメントです。開発者は自分のコードとそれをどのように使用するかについてすべてを知っているので、それを書くのがかなり上手になる傾向があります。説明

説明は、ソフトウェアのより高いレベルの理解に関連する特定のトピックに深く掘り下げたり、議論したりすることです。説明について、Procidaはそれを指摘しています -

ドキュメントのこのセクションが明示的に作成されることはめったになく、代わりに、説明のスニペットが他のセクションに散らばっています。時々、セクションは存在しますが、

の背景やその他のメモなどの名前があり、

は機能に正義を果たしていません。

トピックは、ハウツーガイドのように達成したい特定のタスクや、チュートリアルのようにユーザーに学習したいことによって定義されていません。参照資料のように、機械の一部では定義されていません。これは、一度にカバーしようとする合理的な領域であると考えているものによって定義されているため、議論のためのトピックの分割は少しarbitrary意的です。

あなたが注意を払う必要があるものドキュメントをユーザーフレンドリーで関連性のあるものにすることについてのいくつかの便利なポインターを見てみましょう。
ドキュメントを発見できるようにします
ソフトウェアのドキュメントを見つけやすくするためにいくつかの作業を行うことをお勧めします。可能な限り多くのユーザーがそれを手に入れることができるように、いくつかのSEOテクニックをいくつかのマーケティング戦略と一緒に使用できます。また、ドキュメントに入れたものは、特定の情報の検索を簡単にする構造に整理する必要があります。 Steve Konvesは、ドキュメントを単独でリンクしたツリーでドキュメントを構築することをお勧めします。ルートノードから始まります。これは、関心のあるすべてのユーザーが発見するために明らかな場所に配置する必要があります。他のすべてのアイテムに簡単にアクセスできます。プロジェクトのREADMEファイルは、ツリー全体の優れたルートノードとして非常にうまく機能することに役立ちます。また、ソフトウェアのユーザーからヘルプリクエストを受け取った場合、回答を書き、簡単にアクセスできるFAQページで利用できるようにすることができます。そうすることで、ユーザーの支援に費やす時間が短縮されますが、ユーザーが最も頻繁に必要とする種類の情報をより明確に考えて、最初にそれらを文書化してドキュメントの目立つ場所に保つことができます。
ドキュメントが最新でバグがないことを確認してください

ソフトウェアのドキュメントに簡単にアクセスするのは素晴らしいことですが、ユーザーがそのコンテンツが古くなっているか、サンプルコードまたは指示がバグのような結果につながることがわかった場合、控えめに言ってもイライラします。それでも、Steve Konvesは、ドキュメントをコードの近くに保つことを提案します。たとえば、ソースコントロールなどです。これにより、開発者がコードを更新すると、ドキュメント資料に気付くでしょう。これにより、ドキュメントの更新が発生する可能性がはるかに高くなります。また、バグの発生を最小限に抑えるために、ドキュメントで提供している指示とコードサンプルを徹底的にテストします。
余分なヒントといくつかの一般的な例

ドキュメントで停止しないでください。ブログの投稿は、ソフトウェアとその機能を潜在的なユーザーの幅広い視聴者に知られていることに最適です。ブログを使用して、製品が何をしているのかを明確にし、ユーザーフレンドリーなチュートリアル、ヒントとトリック、ウォークスルー、アップデートの説明などを提供します。フォーラム - 強力なコミュニティが集まって成長することができる。

私の見解でのこの幅広いドキュメントのアイデアの素晴らしい例は、広く成功したJSアニメーションプラットフォームであるGreensockによって実装されています。構造化されたドキュメント、非常に役立つフォーラム、ブログ投稿、簡単なヒントなど。
反応とvue.jsも素晴らしい例としてカウントできます。それぞれのWebサイトにアクセスするとすぐに、ホームページは各ライブラリがクイックキャッチフレーズで何に適しているかを教えてくれ、その後、ライブラリがプロジェクトに最適な選択肢と見なされる理由について詳しく説明します。どちらのウェブサイトも、穏やかな紹介、実例のあるスニペット、短いタスクの初心者がコードの遊び場を使用して達成できるようにすることを威圧的にしなくなります。ヘルプの取得方法、エコシステムに関する情報の表示、ニュースやブログのセクションなどの詳細

JSゾーンを離れて、優れたWebサイトを持つ人気のUIライブラリのフィールドに入るために、Bootstrapを除外することはできません。 BootstrapのWebサイトでは、ライブラリが何に適しているのか、どのように迅速に開始するか、包括的で適切に構築されたドキュメントとブログをすぐに見つけて、ユーザーを新しいものについて最新の状態に保ちます。

結論

良いドキュメントを書くことには課題がありますが、ユーザーがソフトウェアの機能を実装するのがどれほど簡単になるかを考えると、確かに100倍に支払われます。これはあなたのソフトウェアの人気に貢献し、それが魅力的であり、したがって、それを深く学び、その成長、安定性、長期に貢献することに時間を投資することをいとわない開発者のコミュニティを生み出す可能性に開かれています使用法。
ソフトウェアのドキュメントを書くことに関するよくある質問（FAQ）

ソフトウェアドキュメントをユーザーフレンドリーにするにはどうすればよいですか？そして、明確な言語。専門用語や技術用語をできるだけ避けてください。それらを使用する必要がある場合は、明確な定義を提供してください。コンテンツを論理的に整理し、見出しとサブヘディングを使用して、簡単に移動できるようにします。目次と、より長いドキュメント用のインデックスを含めます。複雑な概念を説明するために、図、スクリーンショット、ビデオなどのビジュアルを使用してください。

さまざまな種類のソフトウェアドキュメントは何ですか？および技術文書。システムドキュメントは、アーキテクチャやデータフローなど、ソフトウェアシステムの概要を提供します。ユーザードキュメントでは、ソフトウェアの使用方法に関する指示と、ユーザーマニュアルとヘルプガイドを含みます。技術ドキュメントは開発者向けであり、コードコメント、APIドキュメント、および開発ガイドが含まれています。ソフトウェアのドキュメントを書くために使用できるツールは何ですか？
ワードプロセッサ、ドキュメントジェネレーター、専門ドキュメンテーションツールなど、ソフトウェアドキュメントを作成するために利用できるツールがたくさんあります。いくつかの一般的なオプションには、Microsoft Word、Google Docs、Doxygen、Sphinxが含まれます。ツールの選択は、特定のニーズとソフトウェアの複雑さに依存します。
ソフトウェアドキュメントをより魅力的にするにはどうすればよいですか？。ビジュアルと箇条書きで大きなテキストブロックを分割します。例とケーススタディを使用して、概念を説明してください。必要に応じて、クイズやエクササイズなどのインタラクティブな要素を含めます。

ソフトウェアのドキュメントの一貫性の重要性は何ですか？

一貫性は、ドキュメントの読みや理解を容易にするため、ソフトウェアのドキュメントで重要です。また、ドキュメントにプロのルックアンドフィールを提供します。一貫性は、言語、スタイル、フォーマット、ビジュアルに適用されます。

ソフトウェアのドキュメントを書く際のスキルを向上させるにはどうすればよいですか？他のソフトウェアドキュメントを読んで、それらから学ぶことを読んでください。テクニカルライティングに関するコースやワークショップを受講してください。あなたの仕事についてのフィードバックを求めて、批判を受け入れてください。ソフトウェアドキュメントの最新トレンドとベストプラクティスを最新の状態に保ちます。