Episode 2 - Writing README files

• What’s a README?
• Modern day added formatting. Mostly Markdown, sometimes Restructured Text.
• What to include in a README?
  • Name the project
  • Intro / Summary / Overview
  • Prerequisites
  • Installation instructions
  • Usage instructions
  • Contribution instructions.
  • Credit for important contributors.
  • Acknowledgments of projects you based yours on.
  • Ways to communicate with you or the community.
  • License information.
  • Project status information in the form of badges.

• Making it pretty

  • Logos.
  • Badges (also called shields).
  • can help generate some.
  • Don’t forget screenshots.
  • If you’re feeling humorous, add some emojis.

• Other things to keep in mind

  • Terminology and Nomenclature.
  • Common “Use Cases” or providing examples.
  • Reasoning for important architectural decisions.
  • How to debug.
  • FAQs.

References

• Acknowledge Contributors with allcontributors.org
• Conveying Build and Test Information with Repository Badges
• Generate Shields at shields.io
• Record and Share Terminal Sessions with asciinema.org