-
Notifications
You must be signed in to change notification settings - Fork 19
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Clarify guidance on "Overview" in heading titles #573
Comments
I would favour softening the guidance to allow "Overview" to be used in a title provided that it is not the complete title. |
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 Further, I would review the existing issues first because a) some of them are quite I'm also not really a fan of "softening" if I understand your meaning. Yes, a |
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: For the avoidance of doubt, I would suggest updating the guidance in section 3.1.6 to something like: 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. |
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." |
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:
AND
OR
@daobrien / @sffrench / @julian-cable Any thoughts?
The text was updated successfully, but these errors were encountered: