release note standards

[Oswald Buddenhagen]

moin,

during the review of
https://gerrit-review.googlesource.com/c/gerrit/+/331879 it was brought
to my attention that the release notes often contain some items that
don't add value for the potential readers - for example rather minor
fixes to the documentation. this adds unnecessary cognitive load on
them.

the purpose of this mail is to establish a common understanding of the
"notability threshold" for changes. this is of particular interest now
that every contributor is a release note co-editor due to the
introduction of the respective commit message footer.

imo, the standard should be "is the item actionable in any way?". this
of course implies a full understanding of the target audiences of the
release notes - sysadmins, plugin devs, 3rd party packagers, and end
users.


another thing is noticed is that the release notes use tenses rather
inconsistently. in particular, the use of the imperative ("fix ...")
looks out of place in this context. this should be easily avoidable now
that "recycling" commit message summaries is obsolete. ideal are the
simple past ("fixed foo") and formulations like "foo is now bar".

thanks

[Edwin Kempin]

On Fri, Mar 4, 2022 at 12:56 PM Oswald Buddenhagen <oswald.bu...@gmx.de> wrote:

moin,

during the review of
https://gerrit-review.googlesource.com/c/gerrit/+/331879 it was brought
to my attention that the release notes often contain some items that
don't add value for the potential readers - for example rather minor
fixes to the documentation. this adds unnecessary cognitive load on
them.

the purpose of this mail is to establish a common understanding of the
"notability threshold" for changes. this is of particular interest now
that every contributor is a release note co-editor due to the
introduction of the respective commit message footer.

 

Thanks for bringing this up.

I agree that a common understanding about this is important and that it would

be good to offer some guidance on this.  

imo, the standard should be "is the item actionable in any way?". this
of course implies a full understanding of the target audiences of the
release notes - sysadmins, plugin devs, 3rd party packagers, and end
users.

Yes, actionable items (e.g. caused by changed APIs) are probably the 

most important entries in the release notes, but I think they are not the

only things that should be mentioned. In my opinion it's also important

to inform readers about new features, improvements and bug-fixes so

that admins can understand the value of applying the update. 

I agree that mentioning all small documentation improvements adds too

much noise to the release notes. On the other hand knowing that there

have been more than X minor improvements to the documentation

may be a motivation to do the upgrade.

I'm curious what others think which criteria make a change noteworthy. 

 

another thing is noticed is that the release notes use tenses rather
inconsistently. in particular, the use of the imperative ("fix ...")
looks out of place in this context. this should be easily avoidable now
that "recycling" commit message summaries is obsolete. ideal are the
simple past ("fixed foo") and formulations like "foo is now bar".

+1 Using past tense for release notes footers make sense to me

 

thanks

--
--
To unsubscribe, email repo-discuss...@googlegroups.com
More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/repo-discuss/YiH%2BdT1Wgrd6IRX3%40ugly.

[Oswald Buddenhagen]

On Fri, Mar 04, 2022 at 01:33:43PM +0100, 'Edwin Kempin' via Repo and Gerrit Discussion wrote:
>On Fri, Mar 4, 2022 at 12:56 PM Oswald Buddenhagen <
>oswald.bu...@gmx.de> wrote:
>> imo, the standard should be "is the item actionable in any way?".
>

>[...] I think they are not the

>only things that should be mentioned. In my opinion it's also important
>to inform readers about new features, improvements and bug-fixes so
>that admins can understand the value of applying the update.
>

to be clear, "in any way" includes all these - letting me know that i
can use a new feature, drop a workaround, or pitch an upgrade to
management are all very much actionable items.

one can consider splitting the notes by target audience to maximize
their impact, but this would require committing additional editorial
manpower.

[Edwin Kempin]

On Fri, Mar 4, 2022 at 4:25 PM Oswald Buddenhagen <oswald.bu...@gmx.de> wrote:

On Fri, Mar 04, 2022 at 01:33:43PM +0100, 'Edwin Kempin' via Repo and Gerrit Discussion wrote:
>On Fri, Mar 4, 2022 at 12:56 PM Oswald Buddenhagen <
>oswald.bu...@gmx.de> wrote:
>> imo, the standard should be "is the item actionable in any way?".
>
>[...] I think they are not the
>only things that should be mentioned. In my opinion it's also important
>to inform readers about new features, improvements and bug-fixes so
>that admins can understand the value of applying the update.
>
to be clear, "in any way" includes all these - letting me know that i
can use a new feature, drop a workaround, or pitch an upgrade to
management are all very much actionable items.

Then we are on the same page :)

 

one can consider splitting the notes by target audience to maximize
their impact, but this would require committing additional editorial
manpower.

I think I wouldn't consider doing this at this point.

We want to keep the overhead for contributors as low as possible and 
first collect more experience with the simple model that we have now.

 

--
--
To unsubscribe, email repo-discuss...@googlegroups.com
More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/repo-discuss/YiIvRkldLr9YHEbD%40ugly.

[Luca Milanesio]

On 4 Mar 2022, at 16:00, 'Edwin Kempin' via Repo and Gerrit Discussion <repo-d...@googlegroups.com> wrote:

On Fri, Mar 4, 2022 at 4:25 PM Oswald Buddenhagen <oswald.bu...@gmx.de> wrote:

On Fri, Mar 04, 2022 at 01:33:43PM +0100, 'Edwin Kempin' via Repo and Gerrit Discussion wrote:
>On Fri, Mar 4, 2022 at 12:56 PM Oswald Buddenhagen <
>oswald.bu...@gmx.de> wrote:
>> imo, the standard should be "is the item actionable in any way?". 
>
>[...] I think they are not the
>only things that should be mentioned. In my opinion it's also important
>to inform readers about new features, improvements and bug-fixes so
>that admins can understand the value of applying the update.
>
to be clear, "in any way" includes all these - letting me know that i 
can use a new feature, drop a workaround, or pitch an upgrade to 
management are all very much actionable items.

Then we are on the same page :)

“Actionable” by any of the stakeholders of the release notes:

- Gerrit admins

- Gerrit users

- Development managers

- QA

- SREs

- Security managers

 

one can consider splitting the notes by target audience to maximize 
their impact, but this would require committing additional editorial 
manpower.

I think I wouldn't consider doing this at this point.

Also, how can you really split them? Some sections could be relevant and actionable for more than one stakeholder.

We want to keep the overhead for contributors as low as possible and 
first collect more experience with the simple model that we have now.

+1

Luca.

 

-- 
-- 
To unsubscribe, email repo-discuss...@googlegroups.com
More info at http://groups.google.com/group/repo-discuss?hl=en

--- 
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/repo-discuss/YiIvRkldLr9YHEbD%40ugly.

-- 
-- 
To unsubscribe, email repo-discuss...@googlegroups.com
More info at http://groups.google.com/group/repo-discuss?hl=en

--- 
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/repo-discuss/CACA_R4Lhwv-Hj%3DTUYuZ8b-t5GmONTkmCgTMFtXyQ51jLT5GLyA%40mail.gmail.com.

[Oswald Buddenhagen]

On Fri, Mar 04, 2022 at 04:14:17PM +0000, Luca Milanesio wrote:
>“Actionable” by any of the stakeholders of the release notes:
>

you need to draw a line somewhere to remain relevant for the more common
stakeholders. if someone wants to reproduce functions of the gerrit
community themselves (e.g., on-site QA), then they can read the git log
just as well.

>Also, how can you really split them? Some sections could be relevant
>and actionable for more than one stakeholder.
>

i didn't say that the documents would have mutually exclusive content.

>> We want to keep the overhead for contributors as low as possible and
>> first collect more experience with the simple model that we have now.
>>

i don't think it would be realistic at all to let the contributors do
the classification - from experience it's hard enough for most to switch
to a hypothetical user perspective in the first place. hence i said it
would require additonal editorial (i.e., RM) manpower. i'm not expecting
this to be actually done. it's more about illustrating the point of
drawing a line depending on the target audience.