Hacker News Reader

Comment by rwmj | Hacker News Reader

Please start release announcements by saying briefly what it is! "R is a programming language for statistical analysis" or whatever. Don't assume that people are familiar with every possible piece of software already.

Also pull important stuff to the top of announcement. Were there security issues that need you to upgrade? What are the major new features that would encourage you to upgrade?

For example here's a release announcement I wrote recently: https://www.redhat.com/archives/libguestfs/2020-February/msg...

Free software doesn't usually have an advertising budget, so you have educate people on what your software does at every opportunity you get.

View on HN

This was posted to the r-announce mailing list.

I think it's reasonable to assume that this message was intended for subscribers of that mailing list, and that the people who chose to subscribe already know what R is.

And yet the message appears here, on a general tech news site, and no doubt many other places. Assuming only R-announce readers will see it is plainly wrong.

> For example here's a release announcement I wrote recently: https://www.redhat.com/archives/libguestfs/2020-February/msg....

Request to please start release announcements by saying what really a "Network Block Device (NBD) server" is. Don't assume that people are familiar with every possible piece of software already.

This is a fair point. I think earlier versions did try to explain what NBD is but they were a bit wordy, and just expanding NBD was deemed sufficient. Next time I'll see if I can get that better.

Of course there's a level beyond which you don't really need to go - I wouldn't suggest explaining what Linux is or what software is.

Frankly my reply was just rhetoric, and I don't like the suggestion of explaining the base of things in release notes. If someone is interested enough they would care to look it up. Those who are not interested would skip the notes anyways.

Release notes are usually for people who are already using it.

To be fair, the announcement was posted to the R-announce mailing list, and it seems probable that subscribers would know what R is.

But here we are reading it on a general tech news site.

Thats not the fault of the R developers who wrote a message appropriate for the audience to which they sent it.

And they never imagined that the announcement of a major release of a popular piece of software would go beyond the mailing list?

Should every message be written with all possible audiences in mind?

It's lucky I never said that because obviously that would be stupid. However the release of a major version of a popular piece of software should be expected to go beyond the mailing list - and guess what, it being on the front page of HN all morning proves that exact point.

Reply on news.ycombinator.com