Title/Heading Capitalisation Nitpick

Django Internals Documentation
1

I was just browsing the new features for 5.2 and noticed the section heading “Composite Primary Keys” was title case whereas the other sections were sentence case.

This is in contrast to the topic page which is sentence case “Composite primary keys”

I reviewed the headings for the topics section to see what the established style is and it seems to be a mix of both sentence & title case… some examples:

Title case:

Everything else is sentence case.

It feels quite nitpicky but at the same time there’s some subtle unconscious interpretation of where a reader is at in the docs by the style of text :man_shrugging:

Any documentation experts want to put in their 2¢?

2

It should be sentence cased:

In section titles, capitalize only initial words and proper nouns.

3

Yup section titles shouldn’t be title-cased :+1:

How about page titles? It feels weird to see the main page title not in title case :sweat_smile:

4

To my understanding we’ve always had titles with just the initial capitalisation.
That’s the style guide.

Should we change it, are you asking? No, I’d probably say. (Like Meh. It’s been fine for 20 years. Leave it be.)

5

@shangxiao Thank you for raising this issue. We should definitely aim for consistency with casing in the docs. Would you be interested in preparing a patch for this?

That said, I’d also like to suggest a small clarification in the style guide to make it clearer, especially for non-native English speakers (a second commit would be great). Personally, when I quickly read “capitalize only initial words and proper nouns,” I interpreted it as “capitalize the initial letter of every word,” since the plural “words” implies every word. Maybe we could rephrase it as:

“Capitalize only the first word and proper nouns (e.g., people and place names, brands, etc.).”

wdyt?

3 Likes
6

Maybe an example would help to clarify the wording, and a link to the title-case and sentence-case description:

Sentence case has no wiki-page, but is included here together with title case and start case: Letter case - Wikipedia

7

I want to say yes but I don’t have the time unfortunately :sweat_smile:

RE the clarification, I dunno I’d probably just leave it as is :thinking: You could go far down the English semantics rabbit hole here and I don’t know if it’s worth stressing over.