Switch from all caps to title case or sentence case for headings in documentation

[wenzeslaus]

Most of our section headings in the documentation use all caps:

## DESCRIPTION
...

## EXAMPLES
...

The style comes from unix-style man pages. However, we don't write in all caps for a reason (better readability), so we should switch from all caps. If we really want, turning into all caps is easy and can be done on the fly, e.g., with text-transform: uppercase; in CSS. So, in the source code, we should have a more baseline style than all caps because the opposite transformation from all caps cannot be done on the fly (fully automatically).

Given that our documentation is in English, we have a choice between:

• sentence case and
• title case.

There is no difference for a one-word heading which is our most common case:

## Description
...

## Examples
...

For multi-word heading, there is a difference.

Sentence case:

### Region handling
...

### Changing the CRS of a project
...

Title case:

### Region Handling
...

### Changing the CRS of a Project
...

Sentence case is simpler to get right, but title case makes nicer section headings according to some. The choice becomes more complicated when we consider that on higher levels of headings and titles the title case is more prominent or expected, so we may likely end up using title case in on some levels anyway. This basically creates another option. scribbr.com describes three heading capitalization styles:

• only first words capitalized (sentence case),
• all significant words capitalized (title case), and
• capitalization varies by level (variable style).

For example, OSGeo website uses title case for HTML page titles, main page headings, section headings, and menu items (although not with 100% consistency). Wikipedia, on the other hand, uses sentence case except for titles of works in English, e.g., in references, where it uses title case.

Many of our page headings are actually all lowercase - these are the tool names - but that's a special case, so we would make an exception to either style that tool names (just like function names and other identifiers) would preserve their case (preserve lowercase) even when they are the first word of a title or heading (or sentence).

[echoix]

Title case would make sense. If we wanted to revert, we could use a single css property, text-transform: uppercase; to have the text shown as before. It has the advantage that we can change it as wanted and for what output needed (for example, a different theme, or print layout).

See https://developer.mozilla.org/en-US/docs/Web/CSS/text-transform

Not that "capitalize" doesn't mean that it would follow the English grammar conventions.

The only thing that would change the decision is if we were to translate 100% of our docs. Maybe a sentence case would be easier to translate.

[wenzeslaus]

Strict sentence case

Option 1: Strict sentence case (use sentence case exclusively even for all titles)

## Description
...

### Region handling
...

### Changing the CRS of a project
...

## Examples
...

## See also
...

Description

...

Region handling

...

Changing the CRS of a project

...

Examples

...

See also

...

[wenzeslaus]

Title Case

Option 2: Title case (use title case for all heading and titles)

## Description
...

### Region Handling
...

### Changing the CRS of a Project
...

## Examples
...

## See Also
...

Description

...

Region Handling

...

Changing the CRS of a Project

...

Examples

...

See Also

...

[wenzeslaus]

Non-strict Sentence Case

Option 3: Non-strict sentence case (use sentence case for section headings, but use title case for some titles and top-level headings depending on the context)

## Description
...

### Region handling
...

### Changing the CRS of a project
...

## Examples
...

## See also
...

Description

...

Region handling

...

Changing the CRS of a project

...

Examples

...

See also

...

[wenzeslaus]

Now you can see full examples of all three options and you can use thumbs up and thumbs down to vote for your preferred style. (Community poll for feedback. Anyone can vote.)

[wenzeslaus]

Grassy the Hungry Cow asked ChatGPT:

Grassy the Hungry Cow: When you (ChatGPT) generate text, do you usually generate Title Case for headings or Sentence case?

ChatGPT: I usually generate headings in Title Case, especially for documents, presentations, and structured content. However, if you're following a specific style guide that prefers Sentence case, I can adjust accordingly.