Ask HN: How do I improve boring README page?

* Provide a graphic, if possible, either of the software in use (if appropriate) or a logo of the project. Presenting people with a wall of text is off putting, so it's nice to break it up a bit with some pictures.

* Describe what the project is as succinctly as possible. If I can't figure out what the project is through a stream of buzzwords or vague descriptions and have to go to another source online to know what a project is, this is an abject failure of the README.

* Describe how to use it, either with a short example or a 'quick start' section. This should be the third or fourth section and should be how to actually use the software. The simpler the better.

* Give a brief description of the documentation and provide a link to more extensive documentation.

* Give a brief description of how to install it or contribute to it. This is most likely not going to be a portion of the README that will be most useful to people but for those that it will be, it provides a nice entry point

* Describe the license. This should be the last thing in the README but should be there to clearly mark this is a FOSS project (or not, if that's the case)

The README is there basically as a directory to the project. The things I initially look for are, in this order:

* What is this project (why am here/what is it good for/why should I care)?

* How do I install it?

* How do I use it, once installed (preferably with an example)?

* What is the license?

All the rest is about ushering the person looking at the project to the appropriate, more detailed, portion of the project, be it documentation, issues, usage, tutorials etc.

Also realize that, as a good approximation, there are roughly four types of documentation [0]. My view is that the README should clearly fall in the reference/information oriented section. It's meant to convey information about the project in the most succinct way possible and give pointers to other areas of the project if someone wants more details.

And, if possible, get feedback from people who actually use it.

EDIT: Sorry, I just wanted to add that it's OK to be boring. Excitement is not the purpose of a README. Utility is. It's more like "fundamental infrastructure" than "a fun document to read!" Leave the fun for the tutorials, how-to guides or other resources. The README is there to be the smallest payload for the maximum utility to convey useful information.

[0] https://documentation.divio.com/

1. What does this thing do?

2. How to install this thing.

3. Examples of using this thing along with output.

Don't go overboard with images. A logo, some screen shots or whatever is plenty. Avoid fluff like cute pictures, memes, image macros, emojis or anything that clutters up the readme file in a terminal.

;;;;;;;;;;;;;;;;;;;

;;;;; HEADING ;;;;;

;;;;;;;;;;;;;;;;;;;

or: emoji + heading

plus a rare touch of ascii art for diagrams

EDIT all of the above does not work on HN