この記事では、ユーザーのドキュメントをプログラムのソースコードと共に保存する方法の1つを紹介します。これにより、開発者とユーザーの両方にとって便利です。
多くの人にとって、この記事は「キャプテン」のように見えるかもしれません。 頬に塩水しぶきを感じ、波の音が聞こえる場合は、すぐに読むのをやめてください！
ユーザードキュメント
ソースコードに（コメントの形式で）直接追加されるドキュメントとは異なり、ユーザードキュメントは、私がそう言うことができる場合、より「ユーザー指向」です。 あなたが長い間適切なライブラリを探していて、突然同僚が「あなたに合うかもしれない」と呼んだと想像してください。 GitHubですぐに見つかりますが、どこから始めればいいのでしょうか？ ルートにREADME.mdファイルがあると便利ですが、それをよく理解しても多くの疑問が残る場合があります。 通常は、1つの包括的な例（ライブラリが大きくない場合）またはWebサイトまたはPDFドキュメントの形式の公式ドキュメントへのリンクで終わります。 これらのリソースの1つにアクセスした後、安心してため息をつき、いくつかのページを注意深く読み、上位5つの例を学習し、自信を持ってライブラリを使用し始めます。
ユーザー文書はプロジェクトの顔です。 アクセスしやすいほど、新規性の問題のためにソリューションを学習するというアイデアをあきらめるユーザーが少なくなります。
Webサイトまたはドキュメントをユーザードキュメントとして使用するのは良い解決策ですが、いくつかの欠点があります。
- ドキュメントはプロジェクトとは別であり、ユーザーがプロジェクトにアクセスするのは難しい場合があります。
- ユーザーマニュアルの責任は開発者にあります。 ユーザーがエラーやタイプミスを見つけた場合、ユーザーが（この記事で提案されている解決策に関して）開発者に連絡して、それについて通知することは困難です。
- ユーザーが開発者を支援し、ドキュメントを別の言語に翻訳することを決定した場合、これも問題になります。
- 技術的な理由でドキュメントが利用できなくなる可能性があります（Webサイトが落ちた、ドキュメントへのリンクが失われたなど）。したがって、プロジェクト内にユーザードキュメントを直接保存する利点を納得させようと思います。
テストのように
プロジェクトの単体テストをコードで保存しますか、それとも別のリポジトリに保存しますか？ 通常、それらはテストディレクトリにあり、プロジェクトの不可欠な部分です。 ドキュメントも同様。 これはプロジェクトの一部ですが、テストとは異なり、ユーザーはソリューションのパフォーマンスをテストするのではなく、ソリューションにすばやく簡単に慣れる必要があります。
プロジェクト内のユーザードキュメント用に別のディレクトリを割り当てることをお勧めします。 docsと呼ばれ、mdの拡張子を持つファイルが含まれるようにします（ Markdownを選択した理由については 、後で説明します）。 また、ユーザーのドキュメントに「エントリポイント」を提供すると便利です。これは、ユーザーがこのディレクトリ内を簡単に移動できる目次ファイルです。 このindex.mdファイルに名前を付け、このディレクトリ内の他のファイルへのリンクのリストを作成することを好みます。
例
1. [](./getting-started.md) 2. [ ](./files.md) 3. [ ](./network.md)
また、「クイックスタート」に使用できる「Introduction」ファイル（ getting-started.md ）の使用をお勧めします。 ソリューションの主な機能を簡単かつ簡単に、例とコメントで説明する必要があります。 このファイルの情報は、ユーザーレベルでソリューションの使用を開始するのに十分なはずです。
残りのファイルには、ソリューションのコンポーネントの詳細な説明、使用の詳細な例、およびユーザーが遭遇する可能性のある問題を含める必要があります。 これらのファイルは相互に接続されていない方がよいため、ユーザーは必要と思われるコンポーネントの調査を開始できます。
リポジトリに直接
ユーザードキュメントの準備ができたら、 README.mdファイルをプロジェクトのルートに追加します。これには、ドキュメントの「エントリポイント」へのリンクが含まれます。
例
# Bricks.Cli.Routing , PHP . . ## [composer.json][], [Composer][] . [ ][] Zip . . [PHPUnit][] . ## PHP 5.5 . ## , [][] <Artur-Mamedbekov@yandex.ru>. ## [](./docs/index.md). API [Doxygen][]. [composer.json]: ./composer.json [Composer]: http://getcomposer.org/ [ ]: https://github.com/Bashka/bricks_cli_routing/releases [PHPUnit]: http://phpunit.de/ []: https://github.com/Bashka/bricks_cli_routing/issues [Doxygen]: http://www.stack.nl/~dimitri/doxygen/index.html
これで、プロジェクトをコミットしてリポジトリにアップロードできます。 これがGitHubの場合、ソースコードに加えて、ユーザーは高品質のユーザードキュメントを受け取ります。 例として、記事で提案されているアプローチを使用した、CLIクエリのルーティングの分野でソリューションを提供できます。
すべてのドキュメントはリポジトリにあるため、https：//raw.githubusercontent.com/Bashka/bricks_cli_routing/master/docs/call.mdという形式のリンクを使用して外部から参照すると便利です。Webインターフェイスをここで「ねじる」場合は、ドキュメントを転送することなく、完全なWebサイトを取得できます。 便利ではないですか？
さらに、ドキュメントをdocsディレクトリからdocs / ruディレクトリに移動する場合、ユーザーに新しいディレクトリを追加し、翻訳されたドキュメントファイルをコピーするだけで翻訳してもらいます。
さようなら
小規模なオープンソースソリューションを作成している場合は、この方法でドキュメントを保存してください。 当たり前のように見えるかもしれませんが、それを使用している人はほとんどいません。 おそらく、これはプロジェクトが何人かの人々によって書かれているという事実と、他の人々がユーザーのドキュメントを書いていることが原因です。