Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update guidance for using object names in titles #352

Open
daobrien opened this issue Feb 10, 2022 · 0 comments
Open

Update guidance for using object names in titles #352

daobrien opened this issue Feb 10, 2022 · 0 comments
Labels
enhancement Will improve the guide but is not a bug or blocker.

Comments

@daobrien
Copy link
Collaborator

daobrien commented Feb 10, 2022

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 daobrien added the enhancement Will improve the guide but is not a bug or blocker. label Feb 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Will improve the guide but is not a bug or blocker.
Projects
None yet
Development

No branches or pull requests

1 participant