WritingStyleGuide
WritingStyleGuide copied to clipboard
Update guidance for using object names in titles
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.