search

redhat-documentation / supplementary-style-guide

This project maintains the Red Hat supplementary style guide for product documentation that supplements the IBM Style guide
https://redhat-documentation.github.io/supplementary-style-guide/
Creative Commons Attribution Share Alike 4.0 International
35 stars 74 forks source link

Add guidance for avoiding future predictions #51

Closed bergerhoffer closed 2 years ago

bergerhoffer commented 3 years ago

Is anyone aware of any guidance (in the IBM style guide or elsewhere in Red Hat, like legal?) to avoid predicting the future in documentation?

Typically at least on OpenShift, we avoid saying things like "This will be fixed in 4.7" or even "This will be removed in the next release". If we have to say something at all, we'd usually opt for something like "This might be removed in a future release."

I'm not sure if there is ever a case where it is appropriate to make a statement of something coming in a specific version. Should we add guidance to the supplementary style guide saying that avoid saying that something will happen in a specific future version?

cbudz commented 3 years ago

Hey @bergerhoffer we might want to check as to what legal implications there are around including in documentation any notification of forthcoming fix or enhancement. I know there can be some ramifications in certain circumstances.

roldanbob commented 3 years ago

I don't think that IBM Style explicitly weighs in on mentioning future plans, but in my experience at IBM it was always a requirement that the documentation avoid preannouncing product plans or alluding to possible changes that might occur in future releases. The primary reason for this, as Chris mentions, is that customers can construe that such statements imply legal obligations.

/b

On Fri, Jan 8, 2021 at 11:30 AM Chris Budzilowicz notifications@github.com wrote:

Hey @bergerhoffer https://github.com/bergerhoffer we might want to check as to what legal implications there are around including in documentation any notification of forthcoming fix or enhancement. I know there can be some ramifications in certain circumstances.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/redhat-documentation/supplementary-style-guide/issues/51#issuecomment-756854765, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFU3RCB4F2BC2GSWGLSSYZ3SY4XK5ANCNFSM4U3KXHYA .

--

Bob Roldan

Senior Technical Writer - Cloud Application Development and Services

Red Hat https://www.redhat.com/

broldan@redhat.com M: 617.784.8489 IM: broldan https://red.ht/sig

leswilliams44 commented 3 years ago

Hi, @bergerhoffer. Is there an update on this issue?

bergerhoffer commented 3 years ago

I did happen to see that "How to write about future events (without breaking the legal rules)" was on the word nerds agenda. Looking at the agenda, it looks like @IngridT1 might have raised it with them. So I'd be curious what came/will come out of that discussion - @IngridT1 do you have any updates on this?

IngridT1 commented 3 years ago

@bergerhoffer Word Nerds did not have a great answer for this. This was basically our discussion:

I just now looked up this issue in the new IBM SG, and it warns against future predictions (p. 265).

Do we want to add any further guidance in the Supplemental Style Guide, or is this enough?

bergerhoffer commented 3 years ago

Thanks @IngridT1 that's helpful.

I think that the IBM style guide's guidance is generally good, but I do think that we need some guidance for when we do have to talk about it. A particular example is when things are being deprecated. We do need to give users heads up that we're probably removing something in the next release.

I like the suggestions about "planned" from the word nerds. That is something that I used recently. I usually go with "might be removed in a future release", but my engineer didn't like that because it really is 99% definite that it will be removed next release, so I went with "planned for removal in a future release". :woman_shrugging:

I'm heading out on PTO til the 22nd, but let me think about this a little more when I get back. I can always shoot something out to the legal team to see if they have any direction on this.

cbudz commented 3 years ago

The IBM guidelines listed above align with what was listed on the source page you dug up not long ago @IngridT1

I also agree with @bergerhoffer that we probably do need to craft some stipulation for deprecations. I've worked on projects that included announcements of deprecations in release notes, and it's important for customers to plan for, so I think we should cover that at the very least as part of the supplement to those IBM guidelines.

bergerhoffer commented 3 years ago

This is on me to check with the legal team to see if they have any guidance on this that would help us.

bergerhoffer commented 3 years ago

@cbudz You mentioned last meeting that this might come up for your managed services work. Did you still have bandwidth to reach out to legal on this topic, or should I or someone else reach out?

mportman12 commented 3 years ago

@cbudz any updates on this?

rolfedh commented 2 years ago

@bergerhoffer The "Deprecated Functionality" subsection in the Release Notes section of the Supplementary Style Guide (SSG) has several mentions of future releases like this one:

In <product> <release>, <name of capability> is deprecated. Bug fixes and support are provided through the end of the <releasename or, if unknown, “a future”> life cycle. After which, no new feature enhancements are made. (Optional: You can use <alternative capability> instead.)

We'll need to update this to reflect current policy.

bergerhoffer commented 2 years ago

Thanks for pointing that out @rolfedh, we'll definitely look to see if we have to make adjustments on that once we hear back from legal!

CC @bburt-rh, who has volunteered to move this issue forward.

bburt-rh commented 2 years ago

I've got a ticket in with Legal asking for official guidance. I'll report back when I hear from them.

bburt-rh commented 2 years ago

@bergerhoffer @ndeevy - I got a response from Legal about this issue, and they pointed me to an internal document that provides guidance for corporate communications (I won't provide a link here as the document is on the internal RH intranet; I can send it out via chat if necessary).

In this document are a couple of relevant items:

Section 5(e): On release dates: "We can not provide specific delivery or release dates unless they are set in stone."

Section 6(c) On future plans: "When discussing future events or plans, use words such as 'anticipate,' 'expect' or 'plan.'"

If we want more specific guidance than this, she suggested that we set up a meeting with someone from the Legal team to discuss. Do we need more info than this to write up some draft content for the Style Guide? Or do we need a meeting with Legal before we can take this issue any further?

rolfedh commented 2 years ago

Thank you for gathering those references, @bburt-rh. I think we should mention them in the supplementary style guide, with links to the sources, and update the various templates we use accordingly. For example, in the SSG release notes templates, update the template to say:

In <product> <release>, <name of capability> is deprecated. We plan to provide bug fixes and support through the end of the <releasename or, if unknown, “a future”> life cycle.
bergerhoffer commented 2 years ago

Thanks @bburt-rh! I think that those two items cover it pretty well. I say this is enough to draft a new entry on avoiding future predictions (or however it should be named). Would you mind taking a stab at a PR, or did you want someone else to work on it?

bburt-rh commented 2 years ago

@bergerhoffer I'll draft some content and submit a PR. I may have time to do it later this week, but it's more likely it'll be post Thanksgiving. Does that timing work?

bergerhoffer commented 2 years ago

@bburt-rh This issue has been open since last December. A few more weeks will definitely not hurt :smile: Thank you!

ndeevy commented 2 years ago

Thank you for gathering those references, @bburt-rh. I think we should mention them in the supplementary style guide, with links to the sources, and update the various templates we use accordingly. For example, in the SSG release notes templates, update the template to say:

In <product> <release>, <name of capability> is deprecated. We plan to provide bug fixes and support through the end of the <releasename or, if unknown, “a future”> life cycle.

This change seems logical. One tiny nit: maybe we should say 'Red Hat plans..' rather than 'we'? Could be overkill or wrong and maybe this is a guess at the best legal wording here but it seems a bit clearer to detach ourselves from the company policy.

ndeevy commented 2 years ago

@bergerhoffer @ndeevy - I got a response from Legal about this issue, and they pointed me to an internal document that provides guidance for corporate communications (I won't provide a link here as the document is on the internal RH intranet; I can send it out via chat if necessary).

In this document are a couple of relevant items:

Section 5(e): On release dates: "We can not provide specific delivery or release dates unless they are set in stone."

Section 6(c) On future plans: "When discussing future events or plans, use words such as 'anticipate,' 'expect' or 'plan.'"

If we want more specific guidance than this, she suggested that we set up a meeting with someone from the Legal team to discuss. Do we need more info than this to write up some draft content for the Style Guide? Or do we need a meeting with Legal before we can take this issue any further?

This is great @bburt-rh

Iiuc, this is an update to the release note deprecation/removal templates and another entry to avoid future predictions or promises. If so, sounds great.

D'you think we should we include the entry from IBM that Ingrid pointed to above:

Thanks!

rolfedh commented 2 years ago

Thank you for gathering those references, @bburt-rh. I think we should mention them in the supplementary style guide, with links to the sources, and update the various templates we use accordingly. For example, in the SSG release notes templates, update the template to say:

In <product> <release>, <name of capability> is deprecated. We plan to provide bug fixes and support through the end of the <releasename or, if unknown, “a future”> life cycle.

This change seems logical. One tiny nit: maybe we should say 'Red Hat plans..' rather than 'we'? Could be overkill or wrong and maybe this is a guess at the best legal wording here but it seems a bit clearer to detach ourselves from the company policy.

The IBM SG supports your comment:

"we pronoun Do not use to refer to IBM in technical information, as in "we recommend". Do not use to refer collectively to both the authors and the audience, as in "we can proceed to the next step". Use only in the question portion of frequently asked questions (FAQs), in marketing proposals, or in information that has listed authors and in which the authors describe their own actions or opinions. Uncertainty about the identity of "we", and whether it refers to the authors, product management, or the management of IBM Corporation, can cause a potential marketing or legal problem for IBM."

bergerhoffer commented 2 years ago

+1 for not using "We" in whatever updates we make.

D'you think we should we include the entry from IBM that Ingrid pointed to above:

Future product releases: Avoid claims that are related to the content or timing of a future product or release. (I think it's quite authoritative and clear) and then explain that there are exceptions in cases then advise to use 'plan' or whatever the best wording is ?

I would probably do a combo of this and our legal guidelines. It sounds like it's pretty set that we should not ever discuss specific dates for releases - so that should be straight forward ("Do not..."). But then for anything else, I'd start with something like what IBM says - to avoid discussing future events or plans - and then add what our legal says - but if you must, then use words such as 'anticipate,' 'expect' or 'plan.'

bburt-rh commented 2 years ago

@bergerhoffer @rolfedh @ndeevy - I've written up some draft content for this issue in the following PR: https://github.com/redhat-documentation/supplementary-style-guide/pull/137

Please review and provide feedback when you get a chance. Thanks!

bburt-rh commented 2 years ago

@bergerhoffer Thanks so much for your comments and feedback! I've revised according to your review and pushed the changes to the PR here: https://github.com/redhat-documentation/supplementary-style-guide/pull/137/files. It's much improved with your suggested changes incorporated. Thanks again.

bburt-rh commented 2 years ago

@bergerhoffer @ndeevy I've looked over the PR I submitted, and I realized that we say "Do not refer to specific releases". However do we need to add an exception for deprecation notices? These notices might say something like "This feature is deprecated and will be removed in the next release".

bergerhoffer commented 2 years ago

Hey @bburt-rh sorry I merged your PR before I saw this question :)

We did mention deprecation notices in the intro area. I guess my question is - do deprecation notices have to say "will be removed"? Because I'm wondering if they could still follow our guidance here, and say something like:

Or something similar? I think either way, it would probably be a good idea to put a deprecation/removal example into the section

In the conscious language section, there is an example of having more than one example and a correct and incorrect version of each (using icons). We could consider something like this for having the current example + adding a new deprecation example: https://redhat-documentation.github.io/supplementary-style-guide/#conscious-language

wdyt?

ndeevy commented 2 years ago

That's a really good point @bburt-rh I agree deprecation should be addressed.

In the Release notes doc texts section we also included a template for deprecation or removal notices that shows examples of specific releases. We could add an extra bullet for exceptions like:

Good thinking also, @bergerhoffer looking at the Release notes doc texts section not using future, I'm wondering if that answers some of your question "- do deprecation notices have to say "will be removed"?"
For these, I used present tense but with a future meaning:

Deprecation notice In , is deprecated. Bug fixes and support are provided through the end of the <releasename or, if unknown, “a future”> life cycle. After which, no new feature enhancements are made. (Optional: You can use instead.)

I think your suggestions are better than what's in this section though and maybe I need to revisit those removal/deprecation notices based on the outcome of this conversation too.

bburt-rh commented 2 years ago

@bergerhoffer @ndeevy I can submit another PR that states that deprecation notices are an exception to the "don't refer to future releases rule", and then link to the Release Notes guidance for deprecation notices. What do you think?

ndeevy commented 2 years ago

That would work well, I reckon @bburt-rh

bburt-rh commented 2 years ago

@ndeevy @bergerhoffer Please review https://github.com/redhat-documentation/supplementary-style-guide/pull/140, which contains text about deprecation notices being exceptions to the rule about not referring to specific future releases.

inoxx03 commented 2 years ago

PR #140 merged. Can we close this issue as resolved? Thank you.