WritingStyleGuide icon indicating copy to clipboard operation
WritingStyleGuide copied to clipboard

Update guidance for using object names in titles

Open daobrien opened this issue 3 years ago • 0 comments

Initial question from @nmuller66

Do we have the guidance about avoiding object names in headings documented anywhere? Examples: Virt-Launcher Pods PersistentVolumes PersistentVolumeClaims

Initial suggestion from @daobrien

I'd hazard a guess that almost all of those have a simple "plain English" description that could be used in a title. There might be exceptions (aren't there always?) but I'd need a better look at the content to offer suggestions. I don't see any issue with "Persistent Volumes" or "Persistent Volume Claims"; you'd only use the one-word forms when referring to the actual objects, not the concept.

https://stylepedia.net/style/5.1/#heading-styles > File Names, Commands, and Related Terms goes some way towards addressing this. We could probably just expand it with more examples.

daobrien avatar Feb 10 '22 03:02 daobrien