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

61–70 of 77 posts

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

#61

Post by hutzlibu »

capableweb wrote: post #59
hutzlibu wrote: post #50

Earlier quoted context omitted.

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.

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. That means you start with the easy things.

Like in the case of find, with an example, that looks on a given path for that string.

And if I know that, I can work myself up, if I want to.

But don't bombard people with information they do not need or want. And if people manage

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

#62

Post by capableweb »

eadler wrote: post #60
capableweb wrote: post #57

Earlier quoted context omitted.

> 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

What tar are you running? I'm running `tar (GNU tar) 1.34` and get a `This does not look like a tar archive` error when trying to extract a zip file.

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

#63

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…

Thank you for these pointers. I agree. It's one of those tools that, if you have that problem, you know exactly why you need it.

This solves this issue: https://github.com/minio/minio-py/issues/829. MinIO is an S3 compatible object storage software. https://min.io/

Thanks again. I'll improve the documentation.

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

#64

Post by Jugurtha »

SomeHacker44 wrote: post #43
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?

> bmc is a Python wrapper for MinIO’s command line interface mc and minio. MinIO has a useful client library which unfortunately lacks administrative capabilities, such as adding users and hosts, which we need to do for the iko machine learning platform. No. But I also do not know what MinIO is, nor mc, minio or iko. It also does not say why it is called bmc.

>No. But I also do not know what MinIO is, nor mc, minio or iko.

MinIO is an S3 compatible-ish object storage. `mc` and `minio` are command line interfaces to administer it and launch the server. The project has a Python library that invokes the server to manipulate buckets and objects for specific credentials, but lacks the administrative capabilities that `mc` has, such as adding "S3" policies and managing "users", and cannot launch servers as `minio` does. The library is a "thin wrapper" that makes it possible to manage policies and users with Python.

>It also does not say why it is called bmc.

What does IBM stand for? Nothing. It just sounds professional /s :) [0]

Joking aside, the library is to expose a Python API to a binary named `mc`. The `b` stands for BIGmama Technology. `bmc`

- [0]: https://www.youtube.com/watch?v=Lb0sDIuEf_A

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

#65

Post by Jugurtha »

dale_glass wrote: post #44
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?

No clue here either. My takeway is that it's an extremely specialized piece of software, only of any use to people already familiar with whatever mc and minio are, who hopefully find that explanatory enough. I think this sort of thing is okay if you're targeting very specialized uses. But it is almost definitely too obscure if a newcomer to the field could have an use for it, without yet knowing what tools are used i…

Thank you for the reply. More information in the reply above[0]

- [0]: https://news.ycombinator.com/item?id=26547179

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

#66

Post by eadler »

capableweb wrote: post #62
eadler wrote: post #60

Earlier quoted context omitted.

tar(1) can extract zip files. tar xf file.zip Works perfectly

What tar are you running? I'm running `tar (GNU tar) 1.34` and get a `This does not look like a tar archive` error when trying to extract a zip file.

both

bsdtar 3.4.3 - libarchive 3.4.3 zlib/1.2.11 liblzma/5.2.5 bz2lib/1.0.8 libzstd/1.4.5

and

bsdtar 2.8.3 - libarchive 2.8.3

seem to do the job.

I don't use GNU based tools much so I'm unsure if you need special flags for them.

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

#67

Post by gutbasokchok »

TeMPOraL wrote: post #16

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…

Amazing perspectives to consider. I will keep them in mind

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

#68

Post by xavierlint »

thegabez wrote: post #48

This is a good resource when looking for inspiration https://github.com/matiassingers/awesome-readme

Not only inspiration, there are various linked articles with good suggestions on how to write good readmes: https://github.com/matiassingers/awesome-readme#articles

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

#69

Post by gitgud »

Jugurtha wrote: post #40
TeMPOraL wrote: post #16

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?

Looks pretty good, as others have mentioned it's highly specialised. Seems to be a wrapper for a cli tool named MinIO.

One thing to improve it would be to link the MinIO project at the beginning. A simple hyperlink in the intro will do!

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

#70

Post by hutzlibu »

tomcooks wrote: post #56
hutzlibu wrote: post #50

Earlier quoted context omitted.

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

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.
Post reply on HN