More than just known issues, what should you include in release notes? What do you need to watch out for?

1. Everyone loves release
notes!
Neal Kaplan
@NealKaplan

2. What do I write about?
New features (obviously)
Fixed bugs (also obvious)
Known issues (er...are you sure?)
@NealKaplan

3. New features
Quick summary of the awesome stuff in the release
In order of importance
Stick to the summary: link to more extensive docs for the details
Use descriptive headings!
@NealKaplan

4. Fixed bugs
User-reported bugs
● This can be internal or external users
Use short, meaningful descriptions
Link to your help system?
● Useful for internal users, might be visual clutter for external users
@NealKaplan

5. Known issues (bugs!)
Document the problems your users are likely to encounter
Work with engineering and customer-facing teams:
● customer support & success
● professional services / solutions architects / service engineers
@NealKaplan

6. The politics of release notes
Release notes can be tricky, and much more politically charged than most
documentarians would ever expect (or are prepared to deal with!)
How do you frame new features: more marketing or more technical?
How much I is TMI?
Competitive FUD vs openness
@NealKaplan

7. How do you want your users to learn about
bugs?
From the release notes or when they use the product?
Help your support team! Provide info that they can use
@NealKaplan

8. Internal or external?
Why not both?
● Can you use conditional text?
Avoid having multiple copies of relnotes!
● If you have to have internal-only, reference (not copy) the external relnotes
@NealKaplan

9. The practice of release notes
Pro Con
Automate from task
system
● Relnotes will be up to
date, as long as you run
the scripts
● Single source of truth
● Technical tooling
required
● Need to train people to
write usable descriptions
Use fields in task
system
Completely manual

10. The practice of release notes
Pro Con
Automate from task
system
● Relnotes will be up to
date, as long as you run
the scripts
● Single source of truth
● Technical tooling
required
● Need to train people to
write usable descriptions
Use fields in task
system
● Writers have a single
report to review
● Can specify release
notes a/o guides
● Need to train people to
use the fields
● Need reports that use the
fields
Completely manual

11. The practice of release notes
Pro Con
Automate from task
system
● Relnotes will be up to
date, as long as you run
the scripts
● Single source of truth
● Technical tooling
required
● Need to train people to
write usable descriptions
Use fields in task
system
● Writers have a single
report to review
● Can specify release
notes a/o guides
● Need to train people to
use the fields
● Need reports that use the
fields
Completely manual ● You get to talk to a lot of
people
● Lots of work

13. @NealKaplan

14. Thank you!
@NealKaplan
Come see me speak about documentation triage at the WTD
conference in May!