19

What makes a good README.md for you ?

Comments
  • 11
    If it explains nice and simple and to 100% how to run the shit
  • 8
    0. clearly structured document (0, 1, 2 lvl headers where applicable)

    1. what does it do? what's its purpose? what it's not meant for? Depending on the context, HOW does it do it would also be of interest (e.g. Spring IoC vs Dagger2 projects do the same but in a very different way that makes Spring a poor choice for android whereas Dagger2 is the perfect fit)
    2. dependencies (!!!), if applicable - including actual version numbers
    3. how to install that thing
    4. usage examples would be nice. The "Hello world" part and the most tricky parts.
    5. licence, if applicable

    The best READMEs I've seen have all of the above. In that order. Other sections I usually skip.
  • 0
    You think this is okay, or should I change something?
    https://github.com/thosebeans/dotpm
  • 2
    A link to a working demo if there is something to see, or a gif if it is a cli program
  • 2
    It exists....
  • 0
  • 1
    @metamourge Installation and dependencies parts should be way higher, I almost thought you forgot them since they were so low. At least before "Usage".

    You also have a typo on "dependencies" title (you spelled it "dependecies"
  • 0
    @Fradow, thanks, will change it.
  • 0
    # <title>

    <Fancy badges>

    <Detailed explanation what it is>

    # Installation

    On <platform name>:
    <Shell commands (preferred) or GUI installation instructions>

    # Usage

    <Quick, surface-level "How to use my program" guide>

    # Contributing

    <What and how branches are used, do I need to sign a CLA, etc.>
  • 2
    Examples!
Add Comment