Podcast #128: We chat with Kent C Dodds about why he loves React and discuss what life was like in the dark days before Git. Listen now.
29

Release notes should describe what changed as seen by the users. That doesn't necessarily mean "all the gory technical details", though; as with other technical writing, you want to tell the user what he needs to know (and maybe a little more), but you don't want to overwhelm him with unneeded details. If there are larger themes in a release, you might ...


3

Write for the audience, using whatever voice will best help them understand the meaning and significance of the release notes. If there's more than one audience (e.g. end users and API users), write for them separately.


3

I agree with Mark's points about the distinction becoming less important in the current model of how your audience finds your content. Secespitus alludes to the importance of not annoying your technical audience, which I think is also a good thing to keep in mind. I would take Mark's approach of not making a distinction in voice, as well as making sure ...


2

The idea of letting the developers write the notes will shatter on the cliff of reality. Most developers don't want to write them, so even if you force them somehow, you will only get a mess and not a note. Just for the record: I am a developer. What you can do is just improve your existing workflow a little bit. A little bit often does wonders and you will ...


2

In my opinion Release Notes should be written in a technical style, focused on the technical implications of the most recent changes. This makes them sort of a mix between the two worlds - you want to target decision makers and technical people and tell them what has changed when compared to the older version of the software, emphasizing what the problems ...


1

Release notes should be written in the same voice as the User's Guide, online Help, and other documentation -- if they have the same audience -- because all documentation content (more than "voice") is based on audience needs, comprehension level, and purpose. When I wrote release notes for Citrix Metaframe software, the notes had content, depth of detail, ...


1

It depends on the type of software you're delivering and your audience. I've spend more then 10 years in embedded development and wrote a lot of release notes. In my company, we created the release notes for a new software release directly from the ticket tool. So the content looked like this: Product Name V1.2.3.4 123 - Adjusted IP frame length 124 - ...


1

I'm at a different company now than I was when I asked this question, but the new one had the release-notes problem too. Here is how we solved it (at doc's instigation): When a bug is filed, if it's customer-reported or customer-facing, the "needs release note" box is checked. (There is a triage team that reviews these and might change this, but this is ...


1

Compiling release notes is NOT the job of a single author. It's ideally part and parcel of your source control and project management system. Your developers would have a set of automated tests for all reported bugs and documented features, and any necessary changes would require a change in said test, which could automatically note a change for the ...


1

First off, technical non-writers make better technical writers, than non-technical writers do. They usually can write in a way mostly understandable to layman and factually correct (as opposed to non-technical writers who'll often write something perfectly clear, but completely wrong), they just need to be asked to do so - they won't, if they don't know they ...


Only top voted, non community-wiki answers of a minimum length are eligible