Modern technical writing - Andrew Etter 2016

Catalog the diff
Basics

One of the most important functions of a technical writer is to record changes to a product. Good change logs convince people to upgrade, inspire confidence in the direction of a product, and help developers take advantage of new features. What's new? What's different? What was removed? How do I upgrade? Any "gotchas" to be aware of? If a feature is simple, just noting that it exists is often better than adding new documentation on how to use it; people can figure out how to use simple features without the help of documentation, but not if they don't know to look for them. More than anything else, change logs should be terse, minimalist, and eminently scannable.

Marketing departments often use these documents to write their own, hyped-up copy for advertisements or blog posts, but your own appraisal of differences should use a more neutral tone. In six months, the features described in the change log will no longer be so novel, but they will still be online. Readers shouldn't have to parse a short sales pitch about the incredible potential of a new feature in order to learn that push notifications arrived in version 1.8.2.