[TeMPOraL]

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 honest about when an alternative is a better fit than your project.

- What platforms does it work on? What are the requirements?

- How do I install it? In exact steps, for most common workflows. If that gets too long, link to a separate page containing these detailed instructions.

- How do I run it? Examples of common use cases, with exact invocations/procedures to perform.

- Any relevant remarks that could prevent me from installing or using the software.

- Links to further docs, project webpage, communities, etc.

When I evaluate a project - even briefly, skimming the repo README - these are all the points I'm on the lookout for - they're all helpful for deciding whether to look closer at the project, and possibly install and use it.

[michaelbuckbee]

These are all fantastic suggestions, but I have one more: do a 15 minute user study.

Find someone who might be interested in the project and offer to screenshare with them as they navigate the README and try to get things set up. Note: you just watch them go through this while they describe their thinking and take notes.

I've done similar things and it never ceases to surprise me the how big the gaps are in my view of the project vs someone fresh to it.

[SomeHacker44]

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.

[tpetry]

And if it is something which is mostly intended to be used in a different system or ecosystem say it.

Some time ago one of the big data serialization formats of the apache system was discussed. I didn‘t understand the benefit of it as it looked like all the other ones. But the hn comments had discussed the main benefit: it‘s an in-memory so the different (layered) big data frameworks can directly operate on it without permanent encoding/decoding for the next layer.

[Jugurtha]

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?

[TeMPOraL]

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 know anything about the ecosystem.

Here's what I would improve:

- Fill in the "Introduction" page; right now it's empty.

- Put appropriate links under first mention of "MinIO", "mc" and "micro" - to make it that much easier for people to fill the missing context.

- Is that Python 2 or Python 3 library? Or it works on both? ASCIInema below suggests Python 3, but that's too far down. I'd put the number(s) in the first sentence anyway.

- Where do I get it from and how? What dependencies does it require?

[Jugurtha]

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.

[Jugurtha]

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.

[dale_glass]

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 in that specific area.

[Jugurtha]

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

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

[SomeHacker44]

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

[Jugurtha]

>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

[gitgud]

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!

[gutbasokchok]

Amazing perspectives to consider. I will keep them in mind