12

What information would you expect to see in the github README?

Should everything go in the README? i.e.

  • Introduction

  • Installation

  • Versions

  • User Guide

  • Implementation

  • Testing

  • Related Resources

Or should you just put certain things in the README (Introduction, Installation, Versions) and the other information is best placed in the Github wiki?

Improve this question
5
  • I would put licence terms also
    – py_script
    Jun 24, 2013 at 15:45
  • In overly general terms, there should be enough information to tell me whether the project is useful to me if all I know about it is the name. Don't assume anything about how the reader found it.
    – Keith Thompson
    Jun 24, 2013 at 15:48
  • 1
    This question has a very detailed/good answer here: stackoverflow.com/questions/2304863/how-to-write-a-good-readme
    – Rodrigo Graça
    Oct 6, 2014 at 13:32
  • You can easily provide links to other markdown documents.
    – Thorbjørn Ravn Andersen
    Oct 16, 2022 at 23:45
  • I think this is a matter of opinion and expectations. Some people put high-level architecture in README.md, troubleshooting, faq, some just the how-to-run section.
    – Dawid Pura
    Oct 17, 2022 at 6:48

1 Answer 1

Reset to default
8

I expect to see an introduction and brief overview. There should be something there to convince me that the project solves a particular problem. After reading the README, I should know enough information to know what the project does, what it requires, how to build it, and how to use it. That information doesn't all need to be in the README, but links to that information should be.

Improve this answer
1
  • 3
    +1 for brief. Don't say "README" and then put a bunch of garbage in that doesn't need to be read.
    – Korey Hinton
    Jun 24, 2013 at 16:22

Not the answer you're looking for? Browse other questions tagged or ask your own question.