Speak directly to, not over, the audience. Like, as if you're teaching a friend how to use what you built.
Throw in some humor. Avoid any unnecessary hoidy-toidy or pretentious language.
Ask HN: How do I improve boring README page?
51–60 of 77 posts
Re: Ask HN: How do I improve boring README page?
#52- Include a BRIEF (fits in one screen) visual demonstration of how it's useful. I could see myself using this but it's all bloatware unless I can actually see it in action.
- Include a quick getting started (installation instructions, etc.), even if it's meant for those already familiar with the extension ecosystem. Just a few commands. I don't want to install it via docker, hardly ever. I have my own dockerfiles for that.
- Bullet points in the beginning have a LOT of repetitive content (Apache AGE enables|supports|etc) that turns those really important bullet points into a wall of text.
- You have three different links to docs, one of which seems to be a duplicate. Why would I need docs? For cypher? I already know cypher. For development? What about if I want to hack on the source? Where are those docs? Quick links are always appreciated since I'm almost always going to be on a time budget evaluating things like this.
Just to name a few.
Re: Ask HN: How do I improve boring README page?
#53Speak directly to, not over, the audience. Like, as if you're teaching a friend how to use what you built. Throw in some humor. Avoid any unnecessary hoidy-toidy or pretentious language.
Agreed except for the humor bit. Please don't include humor in technical writing.
The rule of thumb I learned was "avoid anything that ends in -ly" (there are exceptions, but this has always been a good rule).
Re: Ask HN: How do I improve boring README page?
#54Telling what concrete problem you solve already place you ahead of many Apache projects. "single storage that can handle both relational and graph model data". Some short example of usage would be nice too. To illustrate, let's look at summaries of top popular projects (by number of commits, because that's what Apache shows on stats page): > Camel is an Open Source integration framework that empowers you to quickly a…
OP, if you’re using too many adverbs, you’re going the wrong way. The more words ending in -ly I see, higher the chances I’ll just leave the docs right there to find a YouTube tutorial by an Indian dude
This is also my stance. -ly words make me groan and roll my eyes because it feels like you're trying to sell me something instead of letting it sell itself.
Re: Ask HN: How do I improve boring README page?
#55Earlier quoted context omitted.
Well, I feel like maybe READMEs and manpages have two different goals in mind. READMEs often serve multiple purposes: be a introduction, small tutorial, demos and also reference. While manpages have only one goal, to provide a interface for browsing and reading system reference manuals. So yeah, they are dry, because that's the point. They are supposed to be used as references, not as introductions to a subject.
> They are supposed to be used as references, not as introductions to a subject. Assuming 'man' is short for 'manual', this is exactly where man-pages go wrong. Especially as a beginner; reading man-pages is a waste of time. It's so dense and obtuse that reading man-pages almost requires reading a man-page on reading man-pages. For example try to figure out how to extract a zip using tar by using the man-pages.
How do you think me and a bunch of *nix beards learned how to survive without Wikipedia, stack overflow, nice IRC volounteers, or functioning search engines?
Btw, assuming you meant a gzipped tar, it's tar xvfz (mnemonic: XaVier FugaZi), I can remember from memory solely because of good old RTFM and no hand-holding.
Your mileage might vary, but to put it very frankly (and obtusely): if you can't be bothered to learn why should anyone help you, for free?
Re: Ask HN: How do I improve boring README page?
#56Earlier quoted context omitted.
> They are supposed to be used as references, not as introductions to a subject. Assuming 'man' is short for 'manual', this is exactly where man-pages go wrong. Especially as a beginner; reading man-pages is a waste of time. It's so dense and obtuse that reading man-pages almost requires reading a man-page on reading man-pages. For example try to figure out how to extract a zip using tar by using the man-pages.
Or simply how to find a file. I gave up and used the file explorer's search function, because I did not wanted to google it. Just a simple example of the most frequent use cases. Thats allmost all I want, together with a listing of the various flags and short, but useful description .
If you check at the end of the man page, you'll see that usually an info page is mentioned.
Have an online example which illustrates all possible file finding examples you could ever need: https://www.gnu.org/software/findutils/manual/html_mono/find...
Re: Ask HN: How do I improve boring README page?
#57Earlier quoted context omitted.
Well, I feel like maybe READMEs and manpages have two different goals in mind. READMEs often serve multiple purposes: be a introduction, small tutorial, demos and also reference. While manpages have only one goal, to provide a interface for browsing and reading system reference manuals. So yeah, they are dry, because that's the point. They are supposed to be used as references, not as introductions to a subject.
> They are supposed to be used as references, not as introductions to a subject. Assuming 'man' is short for 'manual', this is exactly where man-pages go wrong. Especially as a beginner; reading man-pages is a waste of time. It's so dense and obtuse that reading man-pages almost requires reading a man-page on reading man-pages. For example try to figure out how to extract a zip using tar by using the man-pages.
> Assuming 'man' is short for 'manual', this is exactly where man-pages go wrong.
Why? Manuals come in different levels, not all of them are tutorials/guides, some of them are references. We still call them manuals.
> For example try to figure out how to extract a zip using tar by using the man-pages.
I'm not sure if you're purposefully mixing tars/zips here, I'm gonna assume you mean a "tar-file" instead of "zip" as obviously tar can't unzip a zip file.
Not sure why you're having troubles finding the instructions compared to the thousands of people who managed to find it. Just to refresh my memory (although I know the commands by heart by now), I gave it a try.
1. `man tar`
3. Read through the synopsis, realize I need to specify the archive file with `-f`.
2. Synopsis didn't mention extract, so I search for `extract` as I know I want to extract a file
3. Now I have `tar xf $archive.tar` and I run that. Notice I would like to have some output.
4. Go back to manpages, search for "output" and find the "-v" flag
5. Final command I'm happy with is `tar xfv $archive.tar`
Is that really so difficult? Has the internet ruined peoples ability to search for information themselves and playing around?
Re: Ask HN: How do I improve boring README page?
#58A 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.
Manpages give you the precise info you need.
Info manuals (mentioned in most manpages, usually triggered by info ) are precisely what you're looking for.
Re: Ask HN: How do I improve boring README page?
#59Earlier quoted context omitted.
> They are supposed to be used as references, not as introductions to a subject. Assuming 'man' is short for 'manual', this is exactly where man-pages go wrong. Especially as a beginner; reading man-pages is a waste of time. It's so dense and obtuse that reading man-pages almost requires reading a man-page on reading man-pages. For example try to figure out how to extract a zip using tar by using the man-pages.
Or simply how to find a file. I gave up and used the file explorer's search function, because I did not wanted to google it. Just a simple example of the most frequent use cases. Thats allmost all I want, together with a listing of the various flags and short, but useful description .
Complaining about the manpages for `find` is maybe the worst example you could make, since `find` has surprisingly many examples on its pages. Open the pages and search for `examples` and you'll see what I mean.
Re: Ask HN: How do I improve boring README page?
#60Earlier quoted context omitted.
> They are supposed to be used as references, not as introductions to a subject. Assuming 'man' is short for 'manual', this is exactly where man-pages go wrong. Especially as a beginner; reading man-pages is a waste of time. It's so dense and obtuse that reading man-pages almost requires reading a man-page on reading man-pages. For example try to figure out how to extract a zip using tar by using the man-pages.
> Assuming 'man' is short for 'manual', this is exactly where man-pages go wrong. Why? Manuals come in different levels, not all of them are tutorials/guides, some of them are references. We still call them manuals. > For example try to figure out how to extract a zip using tar by using the man-pages. I'm not sure if you're purposefully mixing tars/zips here, I'm gonna assume you mean a "tar-file" instead of "zip" as…
tar(1) can extract zip files.
tar xf file.zip
Works perfectly