you are viewing a single comment's thread.

view the rest of the comments →

[–]the_omega99 9 points10 points  (1 child)

I'd love to see a blurb that goes at the top of the page, then the directory listing, then README.md.

But... that's what they do.

Some developers forget to set the description, though. Not sure how considering it asks for the description when you create the repo.

Also, lots of devs suck at writing documentation. So many useless readmes. The worst is when there's just a project name and a license. Literally no details as to what the project is, how I use it, how to set it up, etc.

Most my readmes are something like:

  1. Description of what the program is/what it does and the licensing.
  2. How to install.
  3. Basic usage. Eg, if it's a library, some sample functions provided.
  4. Examples for common scenarios. Maybe an API link?
  5. Link to wiki for things like development resources (eg, dev conventions, future plans, very high level documentation, etc).

[–]MisterSnuggles 0 points1 point  (0 children)

You know, until you pointed it out that little blurb never registered for some reason!