I noticed that the headers and titles in the Foreman/Katello guides is title case (Provisioning Hosts) instead of sentence case (Provisioning hosts). The Peer review guidelines linked from the foreman-documentation readme says “Titles use sentence case”.
I think it would be a good idea to adopt this style convention so that the downstream guides look like the other docs, but I realize that the foreman-documentation repo is used for different plugins and projects. Does anyone know of a reason why we can’t use sentence case?
I can’t find the words “sentence” or “case” in the readme you linked. Maybe I am being blind.
Also could you please link to some examples using the wrong case in the final guides?
That being said, titles should use a consistent case style. If that is not the case, it is a bug. Personally I have little opinion on what the preferred case style is, so long as we use it consistently.
“Sentence case” is not mentioned in the readme itself. It is in the Peer review guidelines. The readme contains a link in the Contributing section.
The original source for this guideline is the IBM Style Guide, which d/s docs has to follow.
Example of title case (first word and nouns are capitalized): Preparing your Environment for Installation.
Sentence case: “Preparing your environment for installation”.
+1 to consistency. Right now the Foreman guides are consistent with each other but not with the d/s docs. So they stand out because the rest of the docs use sentence case. I would be willing to fix this issue with small PRs if no one has any objections.
I am just going to ping the @docs team, so they can also weigh in on your proposal.
Maybe just start by opening a single small example PR, and linking it to this thread to get the right eyes on your proposal.
+1 I’d love for foreman-docs to adopt sentence case for headings. The issue has come up in downstream peer reviews.
@apinnick Feel free to submit a PR if you’re up for it.
Great! Since this is a big change, I will submit separate PRs to keep the reviews manageable.