search

StyleGuides / WritingStyleGuide

The official Red Hat guide to writing clear, concise, and consistent technical documentation.
Creative Commons Attribution Share Alike 4.0 International
71 stars 19 forks source link

Updated section about writing titles #492

Closed julian-cable closed 1 year ago

julian-cable commented 1 year ago

@daobrien @sffrench Please review the "Writing Effective Titles" section, which I've updated to reflect the recently changed guidance that Pat announced.

julian-cable commented 1 year ago

I have reverted the ID of that title. @daobrien What other guidance about titles would you specifically suggest to cover? My aim in this PR is to communicate (and publish soon) the changed RHT guidance about writing titles, which Pat has asked for. If there is also a need to widen the scope significantly, then I would suggest having a new issue for it.

daobrien commented 1 year ago

I have reverted the ID of that title. @daobrien What other guidance about titles would you specifically suggest to cover? My aim in this PR is to communicate (and publish soon) the changed RHT guidance about writing titles, which Pat has asked for. If there is also a need to widen the scope significantly, then I would suggest having a new issue for it.

It's not about "other" guidance, or widening the scope; in fact, quite the opposite. The way we're going atm we're reducing the scope, and focusing primarily on our course requirements, which is not what the RH Technical Writing Style Guide is about.

Consider this: 'Activities and subtasks that the student should perform can alternatively use an imperative verb for clarity. Imperative verbs are prescriptive, such as "Create" or "Delete". Example: “Assess the Health of an OpenShift Cluster”.'

This is 100% about students taking a course. It might be useful if you're writing a subsection about procedures or similar, but in general it's too restrictive for my liking. Note also that there seem to be quite a few cases of smart quotes in this PR; where did they come from?

We also need to be careful with our terminology. E.g., in "Configuring OpenShift" or whatever, "configuring" is not a gerund; it's a verb. Gerunds are nouns, or more specifically, a verb form which functions as a noun. It's often easier to just use examples of what works and what doesn't.

sffrench commented 1 year ago

If the purpose is go to add Pats changes then this looks good to me. But for future David's concerns are something we need to think about.

daobrien commented 1 year ago

tbh I disagree with merging this as-is, but I'm only one person. We need more eyes.

julian-cable commented 1 year ago

I will review the wording one more time to see if I can suggest some changes to address your comments. But first I have some project PRs to attend to.

julian-cable commented 1 year ago

I have made further edits. In an attempt to make the guidance more generic, I changed "student" to "user". For the one paragraph that is specific to training, I added an introductory statement to that effect. I have removed the smart quotes (which were probably from content that was pasted from a presentation). @daobrien What do you think now?