Title capitalization in the docs (revisited)

Archive Documentation
1

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

I like the idea, please go ahead.

3

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

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

4

I also suppose to “sentence case”.

5

I’m fine with this pragmatic approach.

6

+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…

7

Yes, please let’s have that “sentence capitalization” style.

A while ago I tried to promote that myself after having done some research on different style guides (Apple, Google, Microsoft). And it turned out the Microsoft style guide was the most appealing one for me. It suggests “sentence capitalization” among other things. https://docs.microsoft.com/de-de/style-guide/welcome/ It’s definitely worth a look. I guess that if we could replace the word “Microsoft” with “TYPO3” in there people would be very happy. As it covers a lot of things and has an extended word list.

8

For next time: I would have loved the Content Group to have been alerted about the discussion before the decision was made. :heart:

Too many styles makes for errors, which makes for inconsistencies. It also makes it harder to move content between different platforms. :slightly_smiling_face:

9

We can still discuss this. I am sorry. My intention was not to ignore the content group. It was to make progress on (the many) open decisions and continue with documentation and find a practical solution.

What I did propose and which seems to be the general consensus is actually making the practice in the docs that have existed for several years “official”.

I did want to use the official standard, that is what I started to use and documented 2 years ago. But in my experience so far it has not been realistic for our documentation. I started with the premise: there is an official writing style guide, let’s use it. But after about 2 years of practically no one using it besides me and just does not seem to make sense (and we talked about this on Slack and I had documented it, see https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/GeneralConventions/ContentStyleGuide.html#rules-for-titles-section-headers)

And I think it is too difficult (or non-intuittive) for occasional contributors to follow. Additionally, we cannot check this, we cannot enforce this automatically (as we can with coding guidelines and commit messages in the core).

If you look at some of the documentation and the title cases you can compare the docs which I have never touched and updated:

e.g. https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/master/en-us/ (this has the “sentence case” that was generally being used)

Almost all titles in the documentation that are now in official title case were changed by me. Meanwhile, new documentation in “sentence case” was added and merged.

Also, the trend in other documentation projects seems to be to rather capitalize less, so our docs will look even less intuitive when documenting and more weird when reading to the average developer.

The “title capitalization” from the “writing style guide” is not simple to use IMHO and checking with capitalizemytitle.com for every title and subsection is extremely tedious.

On a side note: Even with the content style guide and typo3.org there is ambiguity: I had operated on the assumption that all words with 4 or more letter are capitalized in the title:

We do not capitalize articles, prepositions or conjunctions that have fewer than four letters

use the “AP” captialization at capitalizemytitle.com

https://typo3.org/community/teams/content/writing-style-guide#c8483

In that case, words like, “with”, “without” or “from” should be always capitalized in the title.

But these titles were added recently:

capitalizemytitle.com with AP (or even APA) title case would spell this: “Expanding … With Your Help This Spring”

So, even on typo3.org the title case is not used consistently or there is something which I misunderstood or is not clearly documented, any of which would prove my point.

10

I can see that I sent at least one of those articles to publish, and included the error so that is my fault. I would be quite happy if the content style guide across the site adapted sentence case for content titles and subtitles throughout. For all the reasons you state, but also to just be consistent throughout the properties.

I have found Title Case hard to read, confusing and counter-intuitive. One of the issues is that usually, we don’t see sentence case applied throughout. Some styles have “Title Case” and sentence case mixed. For example: APA style is Title Case in Headings 1 and 2, Sentence case in 3, 4, 5, etc. So we’re more used to seeing a mix.

I put the case forward recently, but Mathias’s explanation was this:

There was no convention, but it was tending towards having [capitalization] everywhere. (There was a lot of German capitalization along the lines of “The black Box”.) As TYPO3 doesn’t always specify what header you’re going to render it in, it was also the easier choice to just say “all”. For example, a title in a box might in fact be an H3 or H4. Don’t want proofreaders to have to think about that."
" Mathias Bolt Lesniak 2 months ago

So - MBL’s solution was to pick title case throughout. And this proposal is to pick sentence case throughout.

I’d vote for sentence case for ease-of-use. I obviously can’t figure out Title Case properly on my own because I can’t figure out when to capitalize articles or not :smiley:

11

I don’t have the ultimate answer, and maybe I’m too pragmatic. However, I think it’s important to explore the aim of the style rule.

I don’t think the choice of title capitalization rule should be based on like or dislike, but on chance of success. How do we create the best and easiest way for new community members to start contributing? How do we encourage contribution? What do we expect from contributors? How do we keep consistency?

@nearlythere quotes me correctly above. I’m not wedded to Title Case, but to me it did—and still does—seem the better of two “evils” when trying to choose something that’s easy to get your head around.

If writers don’t follow the style guide, it doesn’t mean the style rules are wrong. It could just as well mean the style guide is too difficult—or that the writers simply don’t care. (Honestly, it’s likely the latter.) Is it anyway the writer’s job to follow the style? I’m happier if people write without rules than that they don’t write at all. The first version is never perfect. Writing is teamwork, and so is proofreading.

A few more considerations:

  • Title Case isn’t more complicated. If you write sentence case, some words must still be capitalized. Given names, of course, but also languages, and—importantly—some internal TYPO3 concepts. With Sentence Case (is it a name and thus capitalized like that?) you have to know what to capitalize, with Title Case, you just capitalize everything.

  • Title Case is the choice of both AP and Chicago, so it’s compatible with style guides used by numerous publishers and news media.

  • Title Case is easier to achieve programmatically. Especially with a limited list of non-capitalized words, it can be done by regular expression. (I really like that limited list, by the way. Much more than AP and Chicago)

Finally, style shouldn’t change often, but when it does change, it should be implemented broadly and consistently. In last week’s marketing sprint (capitalized?) I suggested having the typo3.org style guide fall back on the documentation style guide, and let that fall back on Google’s style guide. Before we get into details, let’s make sure we have a common goal.

12

I think we are pretty much down to the question, what is easier to use.

You have exceptions to the all-lowercase rule, but these exceptions apply to “normal” text as well, so you have to internalize them anyway (e.g. TYPO3, TypoScript, etc.) The change I am proposing above is only for the titles (and headers) to make it more inline with the other text. If we apply all the rules for “normal” text, the spelling should be exactly the same for titles and sentences.

I do think the rules for title capitalization in the “Content writing style guide” are not really simple to follow. Think of non-professional writers, think of non-native speakers. See my examples above. Maybe ask 3 or 4 random TYPO3 contributors / developers who have not followed the discussions. See if they get the edge cases mentioned above right (with words like “is”, “from”, “about”, “with” etc.). That is our main contributor group.

Again, please keep in mind that we have mostly developers and non-native English spekers (not professional writers or even people who write a lot in English) contributing to the documentation. That is a little different than on typo3.com and typo3.org, I guess.

I think most of them do care and would not mind sticking to a few rules, but as you probably know, core and extension developers already have a ton of rules, conventions etc. (naming conventions, coding guielines, commit message rules, etc.) they have to stick to. And this is constantly changing in the core (see the changelogs). I would like to add as little rules as possible in the documentation, keep it as intuitive and simple as possible. In other words: make the rule be inline with what the people would do anyway (unless there are really good reasons for doing it differently).