TurnKey Linux Virtual Appliance Library

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)

You can get future posts delivered by email or good old-fashioned RSS.
TurnKey also has a presence on Google+, Twitter and Facebook.

Post new comment

The content of this field is kept private and will not be shown publicly. If you have a Gravatar account, used to display your avatar.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <p> <span> <div> <h1> <h2> <h3> <h4> <h5> <h6> <img> <map> <area> <hr> <br> <br /> <ul> <ol> <li> <dl> <dt> <dd> <table> <tr> <td> <em> <b> <u> <i> <strong> <font> <del> <ins> <sub> <sup> <quote> <blockquote> <pre> <address> <code> <cite> <strike> <caption>

More information about formatting options

Leave this field empty. It's part of a security mechanism.
(Dear spammers: moderators are notified of all new posts. Spam is deleted immediately)