Live data from Hacker News

Ask HN: How do I improve boring README page?

news.ycombinator.com

31–40 of 77 posts

Re: Ask HN: How do I improve boring README page?

#31
post #13

Some questions I have are - what is this - how do I pronounce the name (note there's a popular crypto tool called "age", which is "pronounced like the Japanese 上げ (with a hard g)") - what are the alternatives (regular postgres, dgraph, neo4j, ...), and how do they compare, along whatever dimensions you like (performance, guarantees, scale, ease of use, license, ...) - what are some use cases that are good for AGE vs…

> - how do I pronounce the name (note there's a popular crypto tool called "age", which is "pronounced like the Japanese 上げ (with a hard g)")

It's utterly ridiculous that a non-phonetic language won out (for now) the race to global lingua franca. Oh well, I guess we're stuck with it.

Re: Ask HN: How do I improve boring README page?

#32
“The distribution should contain a file named README with a general overview of the package:

the name of the package;

the version number of the package, or refer to where in the package the version can be found;

a general description of what the package does;

a reference to the file INSTALL, which should in turn contain an explanation of the installation procedure;

a brief explanation of any unusual top-level directories or files, or other hints for readers to find their way around the source;

a reference to the file which contains the copying conditions. The GNU GPL, if used, should be in a file called COPYING. If the GNU LGPL is used, it should be in a file called COPYING.LESSER.”

— GNU Coding Standards, https://www.gnu.org/prep/standards/standards.html#Releases (June 12, 2020)

“Good things to have in the README include:

1. A brief description of the project.

2. A pointer to the project website (if it has one)

3. Notes on the developer's build environment and potential portability problems.

4. A roadmap describing important files and subdirectories.

5. Either build/installation instructions or a pointer to a file containing same (usually INSTALL).

6. Either a maintainers/credits list or a pointer to a file containing same (usually CREDITS).

7. Either recent project news or a pointer to a file containing same (usually NEWS).”

— Software Release Practice HOWTO, https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp... (Revision 4.1)

Re: Ask HN: How do I improve boring README page?

#33
If you're referencing this: https://github.com/apache/incubator-age

Then I honestly think it's pretty good. Maybe two changes would be:

- Maybe embed one or two use comparisons of some search in plain SQL, and something using age to show what you can get. This both shows the wins, as well as shows people who already know cypher the general idea of how the languages two combine.

- As an incubating project, maybe talk a bit about roadmap. At what point will it no longer be incubating? What's the threshold? What are the risks of using an incubating project?

Re: Ask HN: How do I improve boring README page?

#34
I'll echo what several other people are said. Your README looks really good. I can immediately figure out what your project is about. You're putting supported Postgres releases front and center, which is good.

Some suggestions:

- One thing that obviously can be added are examples, but I wouldn't litter the whole README with examples. Maybe link to an examples page if you have one?

- When mentioning openCypher and AgensGraph, link to the respective project pages. I should not have to use a search engine to understand those references.

Re: Ask HN: How do I improve boring README page?

#35
Add completely unrelated emojis on every line like all the cool JS projects on Github. /s

But for real, nothing wrong with boring READMEs, as long as they do a good job of explaining the important things using relatively simple language. Images, videos, and demos are always a good idea too, provided they are relevant.

Re: Ask HN: How do I improve boring README page?

#36
More explosions? But really, once you explain what the project or thing is about, is it actually boring? Some of the best projects have "boring" READMEs that explain or point to various documents. This is NOT a failure. If they are useful etc are they really boring?

Or are you bored? Maybe that is the real issue?

Re: Ask HN: How do I improve boring README page?

#37
post #5

A suggestion: keep stuff boring. When one is stuck on a problem, maybe with the deadline or angry boss axe pending on her head, last thing she needs is fancy stuff, emojis, gifa or having to sort through marketing crap (not your case but I've seen plenty of those in "fancy projects") Look at manpages, emergency operation manuals, medical procedures and copy the style Use the website for fancy stuff, it's what's its f…

Ok, but maybe not manpages as a guideline.

I seldom find less helpful readme's than manpages. Technical correct, but hard too read with too many details and no simple straight forward example.

Re: Ask HN: How do I improve boring README page?

#39

Put yourself in the shoes of your users. What does a random user visiting your repo want to know? In my case: - What problem does the software solve, and - roughly - how? - How does it look? If it has any visual component, even if it's a CLI interface that's meant for human consumption, screenshots are mandatory. Screenshots + videos/ASCIInemas preferable. - If there are alternatives you know of, mention them - be ho…

Awesome list, thanks.

Also include the first bullet point (what it is, why and maybe how) in every blog post, landing page, release note, news article, etc. It is frustrating to see an HN article about Blahblah v2.7 with Blergity and not be able to figure out what the heck Blahblah is without clicking around a dozen times.

Re: Ask HN: How do I improve boring README page?

#40

Put yourself in the shoes of your users. What does a random user visiting your repo want to know? In my case: - What problem does the software solve, and - roughly - how? - How does it look? If it has any visual component, even if it's a CLI interface that's meant for human consumption, screenshots are mandatory. Screenshots + videos/ASCIInemas preferable. - If there are alternatives you know of, mention them - be ho…

While I have you here, would you give a quick feedback on this: https://big-mama-tech.gitlab.io/bmc/

Do you understand what it does?

Post reply on HN