Clarify guidance on "Overview" in heading titles

[rclee33]

The RHT Style Guide forbids using “Overview” in heading titles (in one section), but then uses "Overview" in a good example of a title that uses a noun phrase (in another section). The examples should align with our guidance; it’s confusing to see “good” examples that go against the guidance in other sections.

Under 3.1.6 Unused Heading Titles, the Style Guide says: "Do not use "Overview" as a title."

However, under 3.2 Heading Styles > Writing Effective Titles, there's an example of a good title that uses "Overview” in a noun phrase, instead of using vague verbs: "Installation Overview".

Is the difference here between using “Overview” alone, VS “Overview of X”? (If that is indeed the case, then this distinction should be clarified.)

I checked with Dave Sacco, and his view was that using “Overview” in headers is not forbidden, but to use it sparingly.

If that’s the case, then I suggest that we:

1. Clarify the guidance in 3.1.6. We could replace the current content with something like: "“Overview” is sometimes used in heading titles, but it should be used sparingly." AND
2. Replace the “Overview” example from section 3.2 > Writing Effective Titles.

OR

3. Perhaps we reconsider our stance on using “Overview”. If we soften our stance, then we would need to update section 3.1.6 accordingly, but we could keep the example in 3.2.

@daobrien / @sffrench / @julian-cable Any thoughts?

[julian-cable]

I would favour softening the guidance to allow "Overview" to be used in a title provided that it is not the complete title.

[daobrien]

It seems fairly clear to me but maybe because I wrote it :)

"Don't use Overview as a title" means exactly that, and not "don't use the word 'overview' in a title". I would avoid the latter as well, tbh. The reasoning remains the same.

Further, I would review the existing issues first because a) some of them are quite old and don't seem to be getting looked at, and b) some of them come very close to the issue you're describing here. E.g., in some places the SG doesn't follow its own rules.

I'm also not really a fan of "softening" if I understand your meaning. Yes, a guide is a guide, not a set of rules that can never be broken. Having a bit of leeway, having exceptions, etc., is one thing, but "soften" to me sounds like "you can do this if you like or maybe that but try not to do this other thing". Maybe that's your way of saying "leeway"?

[julian-cable]

I agree with not using "Overview" as a title on its own. However, I see its use as part of a title in various contexts, and it does not overly trouble me. For example: "Containers, Kubernetes and Red Hat OpenShift Technical Overview" (DO080 course title) "Kubernetes Overview" (an early subheading in a lecture of DO180); I am not sure that "Introducing Kubernetes" would be much better. "OpenShift Container Platform Overview" (a reference to a section title in RH product documentation) The OpenShift UI includes a page named "Cluster Overview".

For the avoidance of doubt, I would suggest updating the guidance in section 3.1.6 to something like: "Use "Overview" in a title only sparingly, and do not use "Overview" as a title on its own."

In Section 3.2, we can indeed remove or replace "Installation Overview" as an example.

I remain committed to resolving instances of where the guide does not follow its own rules, where these come to light, as an ongoing effort; and to tackling older issues as well as newer ones. In the 6.2 release, about half of the issues that were resolved were dated older than the 6.1 release.

[rclee33]

I think Julian's clarification works very well: "Use "Overview" in a title only sparingly, and do not use "Overview" as a title on its own."