Create release notes template

[itsdeannat]

Create release notes template

Before you begin

1. Join The Good Docs Project slack workspace.
2. Read the template contributing process.
3. You are strongly encouraged to join one of the working groups to get valuable support from the community such as mentorship, Git training, and helpful feedback as you contribute to your first template.
4. Request access to the templates repository by joining the #templates channel in slack and posting a request.
5. Assign yourself to an issue for the template that you want to work on.
6. Add the issue to the templates-kanban and move it into the Research-phase column.
7. While it is not mandatory to know Git to start contributing, if you are keen, you can familiarize yourself with basic git commands and understand the workflow for contributing on GitHub.
   :information_source: The template leads also provide free hands-on training on Git to the contributors on an as needed-basis.

Template description

Some notes about release notes:

• Release notes give users context to understand why a change took place.
• They're generally written for an external audience (customer-facing).
• Release notes are educational in nature.
• Product managers, marketing staff, or technical writers may write or contribute to release notes.
• They can communicate new, changed, or deprecated features; they may also include known issues with links to support forums for more assistance.

Content type name: Release notes

Directory: https://github.com/thegooddocsproject/templates/release-notes

Tasks

1. Research examples and identify best practices for writing release notes.
2. Create drafts of the template set deliverables (the template itself and the guide for the template).
3. Contact the template leads to let them know that your draft is ready for community review.
4. Get feedback on the drafts from the community.
5. After making revisions, submit a pull request.

Helpful resources

• Template Contributing Process
• Template deliverables
• Template roles and resources
• The art of writing great Release notes
• How to write release notes: 23 tips, tools, and examples

[camerons]

I suggest also looking at a great 2018 WriteTheDocs presentation on release notes, which includes some very practice tips for the writing process, along with template/style rules.

Source: Learning to love release notes, Anne Edwards.

[tarasweeney]

Thanks for the suggestion.

[rkathrn]

Thank you!

[camerons]

Great meetup presentation on release notes:

• By Sonja McShane, PaperCut Software
• Meetup
• Recording
• Slides PDF

My notes as watching this:

• 3 Cs for good docs:
  • Clear, Concise, Correct, Consistent, Complete
• Different types of release notes
  • Short, sharp sentences is the main type
• Target audience for release notes (defined by PaperCut software)
  • Customers
  • Frontline Support
  • Technical Services
  • Sales
  • Marketing
  • Developer Relations
  • Customer Service
• Why do they read them
  • Details …
• Metrics from papercut showing searches for “release notes”, and page hits
  • 15th most popular link shared by Support (Jan - May 2020), Papercut
• Don’t write release notes for updates customers can’t see
• Release note formula:
  • <added/removed/improved/updated> <what changed that the customer will see or experience>
  • <fixed an issue that caused> <something that went wrong>
• Who should own release notes:
  • Product managers? (Ideally yes, if mature enough)
  • Tech writers?
• Should bug ids be included for bugs that can’t be seen. (Probably yes, maybe reduce emphasis)
• Don’t say “how it was fixed”. It is irrelevant to the reader.
• Q: Why not mention new behavior? Focusing on consistent structure.

Tips:

• Write in the past tense.
  • The problem happened in the past. The problem is now fixed.
• Explain only the symptom(s) you resolved.
  • Don't explain how you fixed it. Customers don't care how it was fixed.
• Explain the benefit to the customer.
  • To make the release note more meaningful. For example:
    • Added support for custom ECDSA certificates
    • Added support for custom ECDSA certificates, a faster and more secure option than RSA for encrypting connections to the Print Deploy server.
• Make the information relevant and meaningful to the customer.
  • Never leave a reader thinking "So...?", “What the?” or "Hmmm, not sure what that means!”

Q: Screenshots / Videos in release notes:

• Extra cost
• Depends on audience. Maybe yes for non-technical audience.

Q: Educating users:

• Training session
• Cheat sheet for developers
• Be around to answer questions

[flicstar]

I just found another resource, may or may not be helpful: How to Write Great Product Release Notes — The Ultimate Guide