Title capitalization in the docs (revisited)

A while ago, I wrote down some best practices and conventions for documenting. One of the topics covered was spelling.

There is a TYPO3 Writing guide which covers how to capitalize titles, so I used that convention.

The TYPO3 Writing Style Guide conforms to AP style title, you can check it out on https://capitalizemytitle.com/

This capitalizes principal words, every word with 4 letters and more and the first and last word in the title.

The problem

  • This is currently simply not being used. When people write new content, they usually use a simple capitalization, which just capitalizes the first word and uses normal spelling for the rest. This would be called “sentence case”:

The other major type of title capitalization standard is sentence case. Sentence case simply means you capitalize the first letter of a sentence, proper nouns, and nothing else (https://capitalizemytitle.com/)

  • Most of our documentation is capitalized in “sentence case” (except for the parts where I patched it up)
  • The TYPO3 title case is not intuitive or easy to use for occasional contributors. What are principal words? Can you tell me off the top of your head how to capitalize “my”, “and”, “her”, “use”, “with”, “more” etc. in a title? Our documentation is mostly written by developers and occasional contributors. It is not written or reviewed by professional writers!
  • fixing this in every patch is extra work and annoying (for maintainers and contributors). Also, it is not being done, currently.

I am not aware of one single standard that is used by most major open source documentation projects, but one observation is that they tend to capitalize less:

My proposal

For the documentation, I would change this and use a different convention for title capitalization. The “sentence case” (as described above).

Thoughts about this?

Migration

  • update “Spelling and Preferred Terms” page in “Writing documentation” (easy to do)
  • change existing docs (a lot of work but not a general problem)
  • communicate this

Motivation

Why bring up this seemingly trivial issue? - Using spelling inconsistently looks unprofessional. It is extra work to change things later if they are not being done consistently in the first place. Complicated rules make contributing more difficult.

2 Likes

I like the idea, please go ahead.

Thanks for caring. +1 from my side. Like the idea. Improves readability.

P.S. Please change the title of this post accordingly :wink:

I also suppose to “sentence case”.

I’m fine with this pragmatic approach.

+1 for a clear norm, 1+ for sentence case and yeah thanks for caring

Reasons and comments:

  • Sentence case makes maintain ability marginally easier if one is to add a paragraph about a topic which was just a sentence beforehand.
  • Additionally sentence case is easier for most who have English just as a second language, as the rules are so few and non-mathematical that using e.g. https://capitalizemytitle.com/ is not necessary anymore.

I wonder if this should be fixed automatically during rendering - I can see a lot of cons there of course, but I also see the major workload to fix it, not only for Core but also for EXT.
Perhaps instead a script which parses the Docs like a linter would be interesting, so before the build process and thus quite atomic pull requests could be created easily…