Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: How do I improve boring README page?

news.ycombinator.com

Post reply on HN
Print view View original

71–77 of 77 posts

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

#71

Post by capableweb »

hutzlibu wrote: post #61
capableweb wrote: post #59

Earlier quoted context omitted.

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.

Sorry I meant locate. But as for find ... are you serious? I said simple example. There are lots of examples, yes, but all do quite complicated stuff (and I had to scroll lots of text to get there). I mean, I can use them, sure, I studied IT. But at that moment, I just wanted to look for one file on all my hd. Not find files with readpermission flag in combination with deleting etc. Imagine a newb. Make things simple…

Yeah, 100% serious. First example from manpages on `find`:

     Simple `find|xargs` approach

       Find files named core in or below the directory /tmp and delete them.

       $ find /tmp -name core -type f -print | xargs /bin/rm -f
Pretty simple to understand what's going on here. `-name` allows you to specify what filename you're searching for, `/tmp` (first argument) is the directory to search in and `-type` helps you select what kind of thing to search for. Remove the last part as you don't care about deleting anything.

It's really that simple. In fact, unsure how it even can get easier. Just because there are complex examples doesn't mean you can understand the snippets you need and ignore the rest.

And no, manpages are not for newbies who don't know how to A) read manuals B) have no idea about unix. They are for people who are looking for specific pieces of data related to a tool they are using, manpages are reference manuals and they will stay like that.

If you need tutorials/guides, there are plenty of other tools for that. I recently found out about the `info` program that does what you're looking for as well.

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

#72

Post by tomcooks »

hutzlibu wrote: post #70
tomcooks wrote: post #56

Earlier quoted context omitted.

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...

Thx, but I successfully used find before and know how to google it. That was my point, googling it is much simpler and straightforward than the manpage if you forgot the syntax.

Indeed, problem is when you don't have internet because your infrastructure is gone and you're the sysadmin. And most importantly, use what you prefer

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

#73

Post by hutzlibu »

capableweb wrote: post #71
hutzlibu wrote: post #61

Earlier quoted context omitted.

Sorry I meant locate. But as for find ... are you serious? I said simple example. There are lots of examples, yes, but all do quite complicated stuff (and I had to scroll lots of text to get there). I mean, I can use them, sure, I studied IT. But at that moment, I just wanted to look for one file on all my hd. Not find files with readpermission flag in combination with deleting etc. Imagine a newb. Make things simple…

Yeah, 100% serious. First example from manpages on `find`: Simple `find|xargs` approach Find files named core in or below the directory /tmp and delete them. $ find /tmp -name core -type f -print | xargs /bin/rm -f Pretty simple to understand what's going on here. `-name` allows you to specify what filename you're searching for, `/tmp` (first argument) is the directory to search in and `-type` helps you select what k…

" I recently found out about the `info` program that does what you're looking for as well."

No, it does not. I am looking for simple straight forward information.

Info does also not provide that in the examples I tried.

There seems a culture problem. Some people like it complicated and as information dense as possible?

Well, I don't. I know how to read very deep technical information if I have to. But I prefer it simple and structured. So I only see the information I want and not all the obscure use cases too. That cost energy filtering it out. Energy I want to use to get things done.

And btw. I was once introduced to Linux with manpages as the way to go. No wonder linux never reached the masses.

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

#74

Post by sergiotapia »

What's the one thing 99% of your users will want to do with your project? Put that front and center, with a clear example of what it looks like.

In your case, what kind of queries will I be able to make with this extension. For example, getting a list of neighborhoods, the houses in the neighborhoods and the pets in each household. All of that in a single graph query, what does it look like? Boom selling point.

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

#75

Post by zzo38computer »

neolog wrote: 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…

> pronounced like the Japanese 上げ (with a hard g)

When mentioning pronouncing in Japanese, I would think that it would be better to use entirely kana, rather than kanji or mixed kanji/kana. (When writing actual words/sentences, I think mixed kanji/kana is better, but for writing pronounciation, I think kana alone is better.) (Note: I don't know so well understanding Japanese, but I can pronounce words written with kana, at least.)

> But the github readme is a first-glance place, and once I've made it to the docs I might not go back to the readme. So the docs need to contain all that information.

At least some of the information, yes. Any information which is relevant to the use of the project should be mentioned in the documentation, including the license, although the documentation might not need to contain screenshots, a list of alternatives, etc.

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

#77

Post by Jugurtha »

TeMPOraL wrote: post #49
Jugurtha wrote: post #40

Earlier quoted context omitted.

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?

I see it's a specialized library. Since I don't do much Python and never worked with modern ML, it's not very illuminating to me. That's fine, as long as the page quickly makes people like me realize this project is not for them, but stays informative for the target audience. Good job on putting a code sample early, and adding ASCIInema videos; these are somewhat illuminating even for a person like me, who doesn't kn…

Done. Clarified a few things without going into infinite regress. Pushed the commits, the docs should auto update after the CI/CD job terminates.

Thanks for the pointers again.

Post reply on HN