Hacker News Reader

Comment by simonw | Hacker News Reader

I wish there was a convention to favor paragraphs over sentences in release notes.

Understanding most of these release notes requires an extremely deep understanding of WebKit and the relevant web standards.

I'd love to see projects invest more effort in expanding these out. Imagine how much more valuable this document would be if each of the bullet points (or just the most important bullet points) had a couple more sentences clarifying what it meant.

(This is one of the reasons I've started trying to publish annotated versions of the release notes for my own projects: https://simonwillison.net/tags/annotatedreleasenotes/ )

View on HN

I completely agree, but as someone who's owned publishing for changelogs on large-ish, often super technical OSS projects, it can be very difficult to explain some of the concepts needed to grok a bugfix or low-level design change even in the span of a couple paragraphs. And more importantly, that context needs to be written by the engineer involved in the change, which means more context == less code work.

That being said, I think some projects do it extremely well. My gold standard for a while has actually been the OSS Dolphin emulator for Gamecube/Wii. They write incredible progress reports[1] every 1-2 months that give phenomenal context on how they found the bug, why it matters, how it works, and what they did to fix it.

Another great example is VS Code[2]. Their context tends to be around changes that are more UX-oriented, but it's still a great way to understand what new value you're getting on every new release.

[1]: https://dolphin-emu.org/blog/2022/02/08/dolphin-progress-rep...

[2]: https://code.visualstudio.com/updates/v1_67

Check out the TypeScript release notes if you like extensively documented notes :-)

The VS Code release notes are great. I always read through them, and reading about a new experimental feature I can enable if I want to try it out always gets me a bit excited. Why can't Windows put those release notes up-front-and-centre when it continually nags me to update?

Oh wow, yeah the VS Code release notes really are superb.

> https://simonwillison.net/tags/annotatedreleasenotes/

Those are amazing. Well done.

Reply on news.ycombinator.com