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.
- 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:
- Symfony docs does not capitalize all words with 4 or more letters, just the principle words, so we capitalize “With” in a title, they don’t. (see their style guide)
- Django uses “sentence case” in titles: Capitalize first word and proper nouns
For the documentation, I would change this and use a different convention for title capitalization. The “sentence case” (as described above).
Thoughts about this?
- 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
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.