From 2c106a6a1eb69b8c55858dd365d10e969d8314ea Mon Sep 17 00:00:00 2001
From: Chris Doherty <chris.doherty4@gmail.com>
Date: Wed, 8 Nov 2023 17:04:03 -0600
Subject: [PATCH] Update notes for CHANGELOG template (#6972)

---
 docs/developer/CHANGELOG_TEMPLATE.md | 51 ++++++++++++++++++++--------
 1 file changed, 37 insertions(+), 14 deletions(-)

diff --git a/docs/developer/CHANGELOG_TEMPLATE.md b/docs/developer/CHANGELOG_TEMPLATE.md
index 27279d6a14b0..1ef845bdbaa4 100644
--- a/docs/developer/CHANGELOG_TEMPLATE.md
+++ b/docs/developer/CHANGELOG_TEMPLATE.md
@@ -1,17 +1,39 @@
-## [Version]
-
-<!---
-* EACH ENTRY SHOULD BE A SUMMARY OF THE CHANGE; BIG CHANGES GENERALLY REQUIRE MORE EXPLANATION.
-* EACH ENTRY SHOULD BE ACCOMPANIED BY EITHER A PUBLIC ISSUE OR A PR (PREFER ISSUES OVER PRS).
-* REREAD ALL ENTRIES FROM THE USERS PERSPECTIVE. WILL IT MAKE SENSE?
-* IF A SECTION CONTAINS NO ENTRIES, REMOVE THE SECTION.
-* IF ALL SECTIONS ARE EMPTY, YOU SHOULDN'T BE DOING A RELEASE!
+<!--
+
+How to use this template
+------------------------
+
+1. Copy the contents into the desired location.
+2. If you're creating the GitHub release, remove the ## [Version]
+3. Add entries to the various sections ensuring you summarise the change; big changes generally
+   require more explanation.
+4. Append an issue or PR to each entry (prefer issues).
+5. If a section doesn't contain any entries, remove the section.
+6. Re-read all changes from the users perspective. Ensure the summary is written so that almost
+   anyone with a foundational knowledge of EKS Anywhere can appreciate what the change means.
+7. If all sections are empty, you shouldn't be creating a release.
+
+When gathering feedback and applying suggestions:
+
+* Re-read the suggest edits in the same fashion as (6).
+* Double check for duplication, punctuation and grammar (ask for help as needed).
+
+General tips
+------------
+
+* Avoid acronyms unless they're accepted industry wide. CRD is domain specific, use Custom
+  Resource Definition instead. I/O is known industry wide as Input/Output so is fine.
+* Use plain language - avoid jargon.
+* Keep sentences concise but clear.
+
 -->
+## [Version](GitHub URL)
 
 ### Must read before upgrade
 <!--
-Discuss things a user _really_ needs to know before they upgrade. Its the kind of thing that if unread could
-be disasterous.
+Discuss caveats a user _really_ needs to know before they upgrade. Its the kind of thing that if
+unread could be disasterous. Perhaps the user needs to execute some commands before or after
+running the upgrade; detail that here.
 -->
 
 ### Deprecation
@@ -26,12 +48,13 @@ Highlight Custom Resource Definition and CLI changes (additions go under Feature
 
 ### Feature
 <!--
-Highlight new additions to Custom Resource Definitions, CLI or any tool we provide for customers.
+Highlight new additions to Custom Resource Definitions, CLI or any tool we maintain for customers.
 -->
 
 ### Tool Upgrade
 <!--
-Highlight all upgrades to tooling. Most of this information comes from the build tooling repo. Format as follows.
+Highlight all upgrades to tooling. Most of this information comes from the build tooling repo.
+Format as follows:
 
 * Tool Name: <from version> to  <to version>
 
@@ -50,12 +73,12 @@ Highlight bug fixes for all applications.
 
 ### Other
 <!--
-Highlight any other changes such as tweaks to behavior.
+Highlight any other changes that would be useful for the user to know.
 -->
 
 ### Supported Operating Systems
 <!--
-List all supported OSs for each provider.
+List all supported operating systems for each provider.
 -->
 
 |                     | vSphere | Bare Metal | Nutanix | CloudStack | Snow  |