search

StyleGuides / WritingStyleGuide

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

Add file naming guidance #611

Closed rclee33 closed 2 months ago

rclee33 commented 2 months ago

I suggest adding the file naming conventions that are described in the DocBook style guide (https://stylepedia.net/docbook/#adding-sections > File Naming Conventions) to our current style guide.

This issue recently came up in Slack, because our current guidance doesn't explicitly state whether dashes or underscores are preferred as term separators in file names and other names. The relevant page in Confluence is the Replaceable Text page, where examples include project names (and similar names) that do include dashes, but this convention is not explicitly stated.

I'm opening this issue for us to discuss where to add this guidance. The (current) Style Guide makes sense to me, but it's possible that Confluence might be a better fit. (My preference is to pick one resource (and not both) to avoid having multiple sources of truth, which causes confusion and creates a maintenance burden.)

@daobrien @julian-cable @sffrench Any thoughts?

julian-cable commented 2 months ago

I think that Confluence would be the better place to add guidance that is specific to RH Training, or the style guide if it is for more generic uses. It seems to me that providing some RHT-specific guidance in Confluence would be the best option here.

rclee33 commented 2 months ago

I think @daobrien agrees, and that works for me, too. I opened a ticket for that project, so we can close this one.