Make long headers easier to read about foreman-documentation

[ekohl]

Short or long headers aren't a problem. Too short or too long is. Question is, what makes it 'too'. You're right that it's very much a case by case thing.

[asteflova]

@apinnick You give good examples of headings that are probably overly specific and, as a result, too long. For example:

Configuring Smart Proxy server with default SSL certificates for load balancing without Puppet

To give examples of headings that are not specific enough (these are currently used in the installation guide):

5.1. Using LDAP
5.2. Using FreeIPA
5.3. Using Active Directory

The issue with overly specific headings is that they are too long. The issue with headings that are not specific enough is that they are misleading (5.2. Using FreeIPA doesn't describe using FreeIPA; it describes how to connect Satellite to FreeIPA to use it as an external authentication source).

Following the 3-11 word limit for headings might help us strike the right balance between these two issues. But it might also lead to minor inconsistencies (while one scenario might be described in 3-11 words including things like for {Project}, another might only fit the 11 word limit without for {Project}).

[ekohl]

@asteflova I think shorter, more focused guides are the answer to the "not specific enough" header problem. If you have an (External) Authentication guide then "Using LDAP" is not so ambiguous anymore.

The more I think about it, the more I end up leaning to splitting up the Installation guide. Instead start with a basic Installation guide and then for every concept (Authentication, SCAP, Puppet, Provisioning, DNS, DHCP, ...) have separate guides that have their own installation section(s).

[asteflova]

This might be useful for reaching a consensus: The RH-SSG guide requires writers to keep headings between 3 to 11 words:

Use clear titles with familiar keywords for customers. Keep titles and headings between 3 to 11 words. Headings that are too short lack clarity and don’t help customers know what’s in a section. Headings that are too long are less visible in Google searches and harder for customers to understand.

[apinnick]

@apinnick
The issue with overly specific headings is that they are too long. The issue with headings that are not specific enough is that they are misleading (5.2. Using FreeIPA doesn't describe using FreeIPA; it describes how to connect Satellite to FreeIPA to use it as an external authentication source).

Maybe I should rename this issue, "Make headers better" :-)

If I had to choose my battles, I would start with headers that are too long, mainly because they are so annoying.

Headers that are too short are less problematic, in my experience, because usually there is enough context (the document itself or an intro paragraph) for the reader to figure out what it means.

[asteflova]

Headers that are too short are less problematic, in my experience, because usually there is enough context (the document itself or an intro paragraph) for the reader to figure out what it means.

Short headings that are not specific enough are also regularly pointed out in d/s peer reviews (crowdsourced minimalism sessions, RHEL editorial reviews, regular peer reviews too -- although there it depends on the peer reviewer).

So yes, the guide in which a section with a short heading is located provides enough context. But also, the style guidelines we're following and the advice we're getting from experienced people through the initiatives mentioned above indicate that short headings are not what we're expected to use.

I think the RH-SSG guide I linked earlier provides reasonable advice that we can apply on a case-by-case basis:

Principle 3: Titles and headings
Use clear titles with familiar keywords for customers. Keep titles and headings between 3 to 11 words. Headings that are too short lack clarity and don’t help customers know what’s in a section. Headings that are too long are less visible in Google searches and harder for customers to understand.

I know that if I, personally, start following it, it'll help me avoid writing long headings that led to the creation of this issue 🙃 while also allowing me to continually fix headings that are too short.