Who is a changelog for?

Most projects have releases, and with each release, we describe what is new/changed/fixed in a changelog file. keep a changelog has a lot of good ideas.

Who is a changelog for? It is for our customers -- those who use whatever we produce. The changelog communicates to our customers what is new and valuable for them in each release.

Once we realize who the changelog is for, then this can influence how we write changelog entries. A few ideas:

• keep it is as succinct as possible (don't waste people's time)

• don't use technical jargon that our customers don't understand

• be humble -- if there are bugs that got fixed, acknowledge they were bugs. Don't try to embellish or gloss over bug fixes by calling them features, etc. People can see right through this.

• explain changes from the lens of benefits to the customer/user, not from the developer's perspective