By Leave a Comment on あなたのGitHubプロジェクトの良いREADMEを書く方法は？

すべての新しいプロジェクトにREADMEファイルを追加する価値があるか、または必要です。 今日はそのようなファイルを書く良い習慣に焦点を当てます-いくつかの例と、すぐに使用できるテンプレートを使用します。

READMEファイルとは何ですか？

README（名前が示すように：”read me”）は、新しいプロジェクトを開始するときに読むべき最初のファイルです。 これは、プロジェクトに関する有用な情報のセットであり、一種のマニュアルです。 は、READMEテキストファイルが表示され多くの様々な場所となります。, しかし、私たちはプログラマのREADMEに焦点を当てます。

ブートストラップgem（Ruby On Rails）のREADMEの例

GitHubに追加されたREADMEファイルは、リポジトリ内のファイルのリストの下に表示されます。

私たちが専門的に働いたり、コーディングを学んだりすると、何度も公共のリポジトリに出くわします。 他の開発者が利用できるライブラリをオープンソースコードとして使用するか、プロジェクトへの貢献、バグの報告/修正、新しい機能の追加を行います。, 確かに、私達はちょうど便利に入って来、良質の解決を提供するのでこれらのプロジェクトを使用します。 しかし、ユーザーフレンドリーな説明、つまり良いREADMEが欠けていれば、それらを使用しますか？

安心してください-ライブラリやプロジェクトのすべての問題に対する潜在的な解決策を見つけるときに、失望の気持ちを知ることができます。

良いREADMEを書くことの使い方は何ですか？

私はあなたがすでにそれを推測できると思います。, 良いREADMEファイルは他の人かのコードを含み、その注目すべきである。 READMEファイルは、GitHubだけでなく、ブラウザ（Googleなど）でも、プロジェクトを取得するために不可欠です。

私はちょうど学習しているので、なぜREADMEファイルを追加するのに気にする必要がありますか？ このコードできる素晴らしいチャンスだと思い、いないのです。

私はコードがあなたのためだけであるとは思わない。 READMEファイルを追加するのは良い動きです。,

ジュニア開発者のためのREADME

さて、最初のプロジェクト以来、READMEファイルを気にする必要がある理由を確認しましょう！

たとえコードがあなたのためだけのものであっても、しばらくしてから戻ってくるでしょう。 良いREADMEは、リコールに時間を無駄にすることなく、プロジェクトを再起動することができます：それはすべてについて何でしたか？

新進のプログラマーにとって、GitHubは通話カードです。 プロジェクトをGitHubで最も収を行いました。, 私たちがかなりの商業経験や見栄えの良い非営利プロジェクトなしでキャリア段階にいるとき、リポジトリの形で私たちの成果のプレゼンテーショ インタビュー中に披露したいいくつかのデモプロジェクトの準備は最高の作品です。

私たちが学んでいるだけで、そこにトレーニングプロジェクトを落としている場合は、彼らの良い説明に注意しましょう。, 非技術的なリクルーターでさえ、私たちが触れた技術を認識し、それが彼/彼女が探している候補者のプロフィールに沿っているかどうかを確認することが

ポーランド語または英語で？

確かに、英語で。 追加プロジェクトの説明は英語の場合でもプロジェクトはポーランドます。 事業の実現は、大学のものとすることとなる免責としてしばしば要求書です。 それ以外の場合は、プロジェクトを英語で記述してください。

README.md -待って、それはすべてのすべての約ですか？,

.md拡張子は単語から来ています：markdown。 テキスト書式設定のためのマークアップ言語です。 たぶん最初は明らかではありませんが、テキストの作成を容易にするためにマークアップが作成され HTML言語では、最も重要な見出しはh1タグになります。 同様に、ドキュメントの見出しの前に#があります。
.md任意のテキストまたはコードエディタ（Notepad、Sublime、Atom、CSなど）でファイルを編集します。).

githubでのmarkdownの使用法とdillingerについて詳しく知ることができます。,ioプレビュー付きのエディタがあります。

良いREADME-初心者マニュアルを書く

オープンa README.md.新しいプロジェクトのファイル。,

ファイルには常に次の要素が含まれていることを確認してください。

  • タイトルと内部タイトル
  • はじめに-プロジェクトの目的
  • 技術
  • 打ち上げ

次のような追加の要素を使用することも検討してください。

  • 目次
  • イラスト
  • 機能の範囲
  • 使用例
  • プロジェクトステータス
  • ソース
  • その他の情報

それはたくさんあります！ 私のプロジェクトについ,

そこにあります-しかし、あなたはすでにそれを認識していません。

タイトルと内部タイトル

タイトルは、ここにあるものを明確に説明する必要があり、通常はプロジェクトの名前です-H1見出しの前に#。 プロジェクトの名前がその内容を開示していない場合でも、それが何であるかを提案する価値があります。

さらに、テキストにはセクションのタイトルと、必要に応じて内部タイトルを含める必要があります。 READMEを一貫性を保つために、他のすべてのドキュメントでも同様に記述します。 私たちのREADMEで。,mdファイル、見出しは#の倍数で書き留める必要があります：

# header H1
## header H2
### header H3
#### header H4
##### header H5
###### header H6


はじめに

はじめに要約のようなものです。 それは私達がプロジェクトのエッセイを読みたいと思わない余りに長いべきでない。 て記述して面白いようにプロジェクトの目的は、何が問題なされる問題もあります。 小さなプロジェクトの場合は、二、三の文章で十分です。

トレーニングプロジェクトの場合は、インセンティブに言及してください。 なぜそれを作りたかったのですか？ 特定の技術を学ぶには？ それはハッカソンプロジェクトでしたか？, それは非営利団体のためでしたか？ それはワークショップやオンラインコースから材料を暗記するために作成されたアプ それは間違いなく、ここで言及する価値があります。

技術

私たちが使用した言語、ライブラリとそのバージョンを書き留めてみましょう。
たとえば、

  • Bootstrap3または4
  • AngularJS1.6/Angular2+/4/5/6
  • PHP5または7
  • Python2.7または3.6
  • Rails4または5

なぜですか？ まず、将来プロジェクトを立ち上げるときに役立ちます。, ライブラリのバージョンは変更され、目立たない変更は後で多くの問題を引き起こす可能性があります。 できたことを嬉しく思い知らの版を使用していたがコードした同ていきたいと思います。

もう一つ：募集。 それは、その候補者のGitHubのアカウントを参照してください。 彼らは解決の質を推定する技術的な知識に欠けているのに彼らは彼らの仕事提供と関連しているキーワードを知っている。 使用される技術の記述は他の候補者の中で際立たせるかもしれない。,

インターンシップには多数の候補者がいて、採用時間が限られているとしましょう。 CVsが選択されている、二つの同様の候補があり、カレンダー内の最後の利用可能な日付があります。 候補者のGitHubアカウントには同じ数のプロジェクトが含まれます。 一つの技術プロジェクト. 第二の候補者はREADMEファイルを追加しないか、彼/彼女のプロジェクトが不十分に記述されています。 あなたはどう思いますか、どの候補者が面接のために招待されますか？

打ち上げ

プロジェクトを実行するにはどうすればよいですか？ いったプロジェクトについて最低限のハードウェアは不要ですか？,
上げたように、この図書館とそのバージョン。 必要に応じて、テクノロジ、起動、およびハードウェア要件をマージできます。 しかし、それを二つのサブセクションに分割すると、特にプロジェクトの立ち上げに集中する価値があります。 そして、そのサイト、アプリケーションなので関係の設定は、地域の環境へのリンクはGitHubのページは展開の申請はHeroku. 入力データが必要ですか？ もしそうなら、どのような形式で？

READMEを改善できる他の要素に焦点を当てましょう。,

目次

目次は、広範なドキュメントの場合に便利です。 これは、見出しへのリンクを持つ単純なリストとして機能します。

そして、それは次のようになります：


イラスト

GitHubはREADMEでグラフィックを可能にします。 技術的な文書は、かなり読みやすく理解できる必要はありません。 イラストは必要ありませんが、私たちのプロジェクトにとっては審美的な価値があります。 アプリケーションのロゴ、図、スキーム、模範的なスクリーンショットを表示, も図書いました。

リポジトリにファイルを作成し、そこにイメージを追加します。 ファイルパスを使用して表示します：!(ścieżka/do/pliku)。 しかし、これらのソースの所有者がドメインからそれらを削除し、ドキュメントから消えてしまうリスクが常にあります。!(url grafiki)

例：私のREADMEファイルに、アルゴリズムがどのように機能するかを説明するブロックスキーマを配置したいと思います。, 私は自分のスキーマを保つ。画像というディレクトリ内のjpgファイル。 私のドキュメントに表示するには、コードを使用します：

!(./images/schema.jpg)

機能のスコープ

機能のスコープを記述する際には必ずしも使用されません。 ウェブサイト訪問カードまたはto-doタイプの単純なアプリケーションの場合、機能のリストは過剰なフォームです。,

一方、to-doリストのような一見単純なプロジェクトは、ユーザーが日付に応じてタスクを登録、記録、分類、タスクへのコメントの追加、ファイルへのデータエクスポートなど、多くの興味深いオプションを使用して拡張することができます。

使用例

再利用可能なコードや独自のライブラリの場合は、プロジェクトの使用方法をマニュアルで提供する必要があります。, これは、コードの断片として動作することができます：

## Code ExamplesTo generate lorem ipsum use special shortcode: `put-your-code-here`

これは次のように表示されます：

プロジェクトステータス

プロジェクトステータスを追加する価値があります-特にプロジェクトがまだ開発されている場合。 それが私たちのライブラリであれば、計画された変更、開発の方向性、またはその開発が完了したことを強調しましょう。

ソース

私たちのプロジェクトがチュートリアルに基づいていたとき、または特定のタスクに触発されたときに情報を追加する必要がありますか？ はい、確かに。

私はそのことに疑問を持っていません。, 私達が様々な源から学び、私達が私達の進歩を文書化するという事実で恥ずかしがることは何もない。 完了しております。多くのチュートリアルを選択し、学習の素材です。 それに変更を提供せずに、まったく学習せずに、ほとんどの場合、thoughlessコピーは起こりません。

私たちのコードが他の誰かのコードに基づいていた場合、そのような情報を追加する必要があります。

たとえば、Rails3tutorialを使ってアプリケーションを書きます。 らに従ってレール5バージョン、新たな枠組みのメカニズム。 確かに、ここで言及する価値があります。,

私たちのコードが別のソリューション/アプリケーションによってのみ触発されたとき、あなたはそれを言及し、あなたが触発された方法、あなたが行った変更、どのような機能が開発されたかを書くことができます。

演習のセットを解決するときは、他の人がその説明を見つけることができる場所を追加する価値があります。 これらのソースに戻りたい場合は、リンクが簡単に表示されます。 このように、彼/彼女の知識を共有した著者は、この材料を準備し、共有するために彼/彼女の時間を費やしても尊重されています。,

その他の情報

著者、連絡先、wwwおよびソーシャルメディアリンクに関する情報、コードが利用可能になるライセンスの種類、またはプロジェクトに貢

良い、読みやすいREADME

上記の提案は私のものです。 最も重要な点は、読みやすさだけです。 徹底したドキュメントは、採用担当者や他のプログラマーの前であなたのリポジトリ 良いREADMEを書くには多くのアプローチがあります。, 次の例を見てみましょう：

  • Node-chat–簡単な説明、アプリケーションのスクリーンショット、使用例
  • WebApp–APIを使用してウェブサイトとアプリケーションのランディングページタイプのために提供される説明の素晴らしい例。 説明それがどのように動作するか、スクリーンショット、このソリューションで採用された技術、実装される機能に関する追加情報
  • Pomolectron–私たちは、ロゴ、スクリーン, テーブルのコンテンツでナビを容易にするた画面、機能情報はどのように支援アプリケーションの開発

READMEテンプレート

ますの例を以下に示しますREADME.mdファイルテンプレートできるダウンロードできます。 その書式を見て、生のバージョンをあなたのものにコピーしてくださいREADME.md ファイル。

この記事はポーランド語でも利用可能ですFlynerd.pl ブログ。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です