Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
    
I would put licence terms also –  py_script Jun 24 '13 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 '13 at 15:48
add comment

2 Answers

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.

share|improve this answer
    
+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 '13 at 16:22
add comment

I would have:

  • Introduction (one sentence/paragraph if possible)
  • Installation
  • User Guide
  • Related Resources

I would not have (other than links to it):

  • Versions. Perhaps high level but for the most part leave out the history.
  • Implementation. I might change this to 'example' and include that.
  • Testing. Mostly (only) if you expect contributions.
share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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