良いレシピのレシピ

良いプロジェクトReadMeは、コードドキュメンテーションで良い練習であり、また、仕事を探すときに目立つのに役立ちます.ここではいくつかのヒント＆トリックを書くためです.

目次:

Write it well

Include title, description and table of contents

Explain setup and stack

Know your audience

Mention the license

Shout out contributors

Invite contributions

Explain next steps

1 .よく書きなさい。

良いドキュメンテーションは退屈でないか、近づきません.全く反対-グッドドキュメントは、ユーザーが書かれているに従うことは簡単になります.あなたは技術語彙を必要としない-実際には、それなしで良いです.簡潔な英語は十分です.実際、人々がなぜ好きであるかReact docs 彼らはとてもよく書かれているので、良いリンクを持つ、消化された塊に分割、平易な英語で書かれています.
また、自分自身の詳細な類推を見つけることができます.私の学生は、見つけるために本当に興奮しましたthis bit さもなければかなり退屈で技術的なRubyドキュメントで.

2 .タイトル、説明、目次

彼らは簡潔で、プロジェクトが何であるかについて反映しなければなりません.私が書いたReadmeは、ここにありますCovid-19 risk calculator , 私が取り組んだプロジェクトの一つ.あなたはプロジェクトから期待するものを得るから知っている.また、付属の目次は、ユーザーが適切なセクションに移動することを容易にします.

セットアップとスタック

誰もがあなたのアプリケーションのスタックに精通していると仮定しないでください、または彼らはそれをどのように始めるかを覚えている.Repoのクローン方法、依存関係のインストール方法、およびプロジェクトの実行方法を説明します.ユーザーがあなたのコードを操縦する際により独立していることができるように、テクノロジーのドキュメントへのリンクを含めてください.

聴衆を知る

あなたは誰のためにReadMeを書いていますか?プロジェクトを引き継ぐもう一つのdevのためですか?プロジェクトを引き継ぐもう一つのdevのためですか?募集係?それとも、後で良いドキュメントのために?ここではいくつかの例ですreadme 私は別のデモグラフィックを念頭に置いて書いた

for other devs

for general documentation

for beginners to follow along

for recruiters

ライセンス

たとえあなたが常にプロジェクトに完全な権利を持っているとしても、それについて明確にするのは良いことです.このページは役に立つchoosing an appropriate license .

出資

あなたのプロジェクトがオープンソースであるならば、あなたがあなたのプロジェクトに貢献したい将来について、あなたはそれをする方法を指定します.これは通常、私はそれをフレーズ:

Pull requests are welcome. Please make sure that your PR is well-scoped.
For major changes, please open an issue first to discuss what you would like to change.

投稿者

これは、人々と協力するときに便利です.最近気づいたKent C. Dodds 彼のプロジェクトの貢献者を紹介する非常に美しい方法を持って、私は彼からインスピレーションを取った.このコードスニペット:

<table>
  <tr>
    <td align="center">
      <a href="https://github.com/sylwiavargas">
        <img src="https://avatars2.githubusercontent.com/u/45401242?s=460&u=2efe4366e8a6c7e8732daaaf8373250e7c8cfdd9&v=4" width="200px;" alt=""/><br/><sub><b>Sylwia Vargas</b></sub>
      </a><br />
      <a href="https://github.com/sruti/covid19-riskfactors-app/commits?author=sylwiavargas" title="Code">💻</a> 
      <a href="https://github.com/sruti/covid19-riskfactors-app/commits/master/README.md" title="Documentation">📖</a> 
      <a href="https://github.com/sruti/covid19-riskfactors-app/issues/created_by/sylwiavargas" title="Bug reports">🐛</a>
      <a href="#ideas-sylwia" title="Ideas, Planning, & Feedback">💡</a>            
    </td>
  </tr>
</table>

このテーブルの結果

_{Sylwia Vargas}
💻
📖
🐛
💡

次の手順

または“既知の問題”.次のif timeが可能かどうかを記述します.これは、あなたがプロジェクトが完了しているか完璧なことを知っている自己認識のDEVであることを示すための機会です.
ルーカスEttore Chieeguiniからの写真Pexels