How to write a good changelog

In a nutshell, think of your users.

They read top to bottom. They have a very limited attention span. Even if they read all the way through, they're probably going to pay more attention to things that come early. Before patience runs thin.

So your goal is not only to describe changes but to figure out now to communicate as much value to users before they lose interest. If you do a really good job, you might actually prevent them from losing interest and they'll read all the way through. Don't bet on it though...

Tips:

• Start with the interesting stuff: put the most valuable, easiest to understand changes at the top. Push less interesting, technical stuff down to the bottom.

• Zoomability principle: group related changes under a summary title that makes it easier to understand the contained elements, provides motivation to read their contents, and primes expectations.

• Fewer assumptions: try to assume less regarding details users should be familiar with (e.g., the name of a module). Imagine you have a budget that limits how much detail you can get into. Reserve detail only for the most important things.

• Whitespace: add whitespace to bring out the structure in text and make it look less busy.

• Summaries: adding summaries can make things easier to understand with very little additional effort. In the context of a changelog this can be as short as one word.

  Example:

  bind postfix MTA to localhost

  vs

  bind postfix MTA to localhost (security)