それは、開発者が知る必要があり、かつ、開発者から直接受け取ることができないすべての側面を含んでいなければならない。 コード.これらのファイルには、開発上の注意事項、完全なデプロイ手順、外部との統合に関する記述などが含まれます。この投稿では、パワフルで美しく、読みやすいREADMEファイルを作成する方法を説明します。 プロジェクト.

よく準備されたプロジェクト・ドキュメントの素晴らしい紹介は、githubのガイドにある： https://guides.github.com/features/wikis/. これは、「READMEは、開発者がプロジェクトの使用と貢献を開始するために必要な情報のみを含むべきである」と述べている。

このことを念頭に置いて、コーデストでプロジェクト・ドキュメントを作成する際に遵守しているコンポーネントとベスト・プラクティスのリストを紹介しよう。

簡単な紹介

- プロジェクト名これはREADMEの必需品だ。

- ステータス・バッジもし外部のコード品質測定や自動テスト、その他のツールを使っているのであれば、ドキュメントの冒頭は、それらが機能するかどうかを他の人に示すのに良い場所だ。

- 説明プロジェクトについて、主な目的とその活動を手短に説明するための文章を数文入れる。

目次

コンテンツ・リストは長いドキュメント・ファイルには便利ですが、READMEが非常に簡潔であれば必要ありません。

一般情報

- セクションについてユーザー、その役割、より分かりにくいケース、スクリーンショットなどの情報が含まれるかもしれません。

- モックアップUI/UXモックアップのリソースがあれば、リンクを貼っておきます。

• その他の情報 サーバーへのアクセス または 外部APIとの統合例としては、ステージングインスタンスのURLアドレス、共有された機密性のない（！）アクセス認証情報、ドキュメントへのリンク、いくつかの指示などがあります。

インストール

- 必要条件外部ツールのインストールなど、アプリケーションのセットアップを開始する前に満たす必要のある前提条件。

- セットアッププロジェクトを立ち上げ、実行するためのステップバイステップのインストラクション。

- 設定ローカル設定がどこに保存されているかを説明し、あなた自身の設定を受け取る方法を説明します。

- ローカル設定もし、ローカル・セットアップが必要なケースがあれば、ここで説明するのがいいだろう。

開発

このセクションは、機能開発、バグフィックス、ホットフィックス、共通機能、テスト、スタイルガイド、コード整理、プロジェクトで使用する他の開発ツール（例：ガードやドッカー）などの指示を行うのに理想的な場所です。プロジェクトで使用するすべてのルールも忘れずに書いてください。 チーム メンバーは知っておくべきだ。

配備

各環境に対する明確なステップバイステップの指示と、デプロイメントを行う際に「知っておくとよい」すべてのことを提供する。

その他のセクションのアイデア

- APIドキュメント

- 変更履歴

- 外部リソース役に立つかもしれないあらゆる種類のリンクのための場所。

- アプリケーションスタックプロジェクトで使用するアプリケーションスタックのリストです。

チーム

現在のプロジェクトチームのメンバーを表示する必要があるかどうかは議論の余地がありますが（githubはデフォルトで貢献者の全リストを提供しています）、プロジェクトの作者の一人として自分の名前が表示されていれば、いつでもうれしいものです。もし表示するのであれば、できるだけ最新の状態にしておきましょう。

最後に一言

覚えておいてほしいのは、それぞれのプロジェクトはユニークであり、そのドキュメントもユニークだということだ。READMEを書くための素晴らしい解決策は一つもありません。ただ、一般的なヒントに従うこと、そして最も重要なことは、READMEにもつながるリファクタリングについて常に覚えておくことです。何か別の方法で表示する必要がある場合は、常にドキュメント全体を見て考え直すのがよいでしょう。

もうひとつ、"指示 "は重要なので、たくさん書いてください。ありがとう！

続きを読む

• オープンクローズの原則。使う必要があるのか？
• 良質なコードを書くには？
• Vuelendar。Vue.jsをベースにしたCodestの新しいプロジェクト。