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

41–50 of 77 posts

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

#41

Post by michaelbuckbee »

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…

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.

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

#42

Post by capableweb »

hutzlibu wrote: post #37
tomcooks wrote: 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.

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.

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

#43

Post by SomeHacker44 »

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?

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

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

#44

Post by dale_glass »

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?

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.

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

#46

Post by tpetry »

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…

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.

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

#47

Post by legacynl »

capableweb wrote: post #42
hutzlibu wrote: post #37

Earlier quoted context omitted.

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.

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.

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

#49

Post by TeMPOraL »

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?

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?

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

#50

Post by hutzlibu »

legacynl wrote: post #47
capableweb wrote: post #42

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

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