Expand on the good changelog/bad changelog documentation examples

[ci skip]

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index ff9a4fc4fec..ce39a379a0e 100644
--- a/doc/development/changelog.md
+++ b/doc/development/changelog.md
@@ -51,14 +51,34 @@ making it both concise and descriptive, err on the side of descriptive.
 - **Bad:** Go to a project order.
 - **Good:** Show a user's starred projects at the top of the "Go to project"
   dropdown.
+
+The first example provides no context of where the change was made, or why, or
+how it benefits the user.
+
 - **Bad:** Copy [some text] to clipboard.
 - **Good:** Update the "Copy to clipboard" tooltip to indicate what's being
   copied.
+
+Again, the first example is too vague and provides no context.
+
 - **Bad:** Fixes and Improves CSS and HTML problems in mini pipeline graph and
   builds dropdown.
 - **Good:** Fix tooltips and hover states in mini pipeline graph and builds
   dropdown.
 
+The first example is too focused on implementation details. The user doesn't
+care that we changed CSS and HTML, they care about the _end result_ of those
+changes.
+
+- **Bad:** Strip out `nil`s in the Array of Commit objects returned from
+  `find_commits_by_message_with_elastic`
+- **Good:** Fix 500 errors caused by elasticsearch results referencing
+  garbage-collected commits
+
+The first example focuses on _how_ we fixed something, not on _what_ it fixes.
+The rewritten version clearly describes the _end benefit_ to the user (fewer 500
+errors), and _when_ (searching commits with ElasticSearch).
+
 Use your best judgement and try to put yourself in the mindset of someone
 reading the compiled changelog. Does this entry add value? Does it offer context
 about _where_ and _why_ the change was made?