Hacker News Reader

Comment by kumarsw | Hacker News Reader

Looks cool. If the poster is affiliated with the project, some suggestions:

1. I don't know what I am looking at with the examples. I think that this is an interactive session with the program, but this is not clear. 2. It is also unclear how to start the program as the executable name is not specified. This and the former point could be addressed by including one of those gifs of an interactive session that are popular in GitHub readmes these days. Sure, they are a bit gimmicky, but still useful. 3. It is not clearly stated if this is an executable program or a library. I believe it is the former, but this is nowhere in the introduction. 4. Probably this is included with a number of package managers. If that is the case, instructions for installing via a package manager would be helpful, especially since the name is not particularly unique.

View on HN

No please don't use a gif. That's a terrible way to present information and leads to accessibility issues in documentation where it has no business. Instead, just show a shell prompt and the command needed to launch the program.

So long as those with disabilities are also accounted for, using gifs are a great way to demonstrate usage. I always appreciate running across them when I hit a readme.

Out of curiosity, what makes gifs better than static text for you?

I dislike them, but I see one benefit: they increase effective screen real estate by leveraging time as an additional dimension.

I guess they also allow you to passively view a sequence of stuff instead of having to actively scroll to move through the sequence. Maybe that feels easier to some people.

I see how they're useful, but I'm still not fond of them because:

(1) Often, the speed is wrong. Either they play too fast to follow along or they play too slowly and time is wasted waiting for it to show me the part I care about (or loop back around).

It's hard to get the speed just right. And AFAIK browsers don't offer controls to adjust the speed, and even if they did, it would be tedious.

(2) Personally I find animations (especially rapid or looping ones) quite distracting when trying to read the rest of the page. My eye just keeps moving to the thing that's trying to grab my attention.

I usually try to work around that by scrolling so that the animation is out of view. So, I'll live, but it's not a good user experience. And again, (some?) browsers seem to offer no help, like a setting to always enable animation controls (play/pause/etc.) or to loop only once.

There's a link to the documentation [0] right on the page. The documentation is very clear.

People should read their package manager's documentation for help using their package manager.

[0] https://www.gnu.org/software/units/manual/units.html

I agree with you, but package names aren't predictable. I find that an example of installing a package is helpful even for users familiar with use of package managers as it gives context and helps readability. Whenever I see `sudo apt-get somethingsomething` I immediately know that somethingsomething is the package name.

It's an old GNU tool. The package name will be "units" everywhere.

On Homebrew, at least, it's `gnu-units`.

If you try to install just `units`, brew is smart enough to suggest it, however.

Application developers typically do not decide package names (unless they provide their own package repository), distribution maintainers do. Package names may change over time, and might be different for different distributions (or even between different versions of the same distribution), even if they use the same package format.

Of course, application developers may decide anyway to keep track of package names for their N favourite distributions and display them on their website. But to me it comes across as a waste of useful space.

This is a GNU implementation of an old UNIX tool. It’s older than Linux, let alone package managers. There’s also BSD and other implementations available (the BSD version comes pre-installed on macOS).

This isn’t some new tool that is uncommon in UNIX systems, it’s something that a lot of OSs ship with their base install and have done for several decades.

The reason why that matters is because documentation was very different back then. People relied on ‘man’ pages and physical binders with printed instructions. READMEs did exist but they were plain text (not even markdown) and that was generally just there to explain how to compile the source (the compilation would create man pages)

> the BSD version comes pre-installed on macOS

As discussed elsewhere in the thread (https://news.ycombinator.com/item?id=25659223), it looks like macOS uses an early version of GNU Units.

Ahh yes, before it adopted GPL. I should have spotted that because it’s very typical of Apple hehe

Maybe a shell script showing the inputs more explicitly would help?

    echo -e '500 miles\nkm' | gnu-units-executable-name

But I'm pretty sure from reading the post that units prompts you first for 'you have' (units and/or measurement to convert) and then prompts you for 'you want' (units to convert to).

Reply on news.ycombinator.com