Review 'contribution guide' in CONTRIBUTING.md #4294
Conversation
Its contents are better described as 'conventions' rather than 'style'
github-actions
bot
added
Needs tech review
| * The AsciiDoc and RedHat style packages for the Vale linter. | ||
| See [Vale for writers at Red Hat](https://redhat-documentation.github.io/vale-at-red-hat/docs/main/user-guide/introduction/). | ||
| * [Red Hat supplementary style guide for product documentation](https://redhat-documentation.github.io/supplementary-style-guide/) | ||
|
|
There was a problem hiding this comment.
I thought about adding the IBM style guide but didn't because 1) it's not available to the public 2) a lot of the rules are included in the Vale rule sets.
|
The PR preview for 935e17b is available at theforeman-foreman-documentation-preview-pr-4294.surge.sh No diff compared to the current base |
CONTRIBUTING.md
Outdated
| * User input is surrounded by underscores (`_`) to indicate variable input, for example, `hammer organization create --name "_My Organization_" --label "_my_organization_"`. | ||
| * Links to different guides are followed by the title of the guide in italics, for example `in _{ManagingHostsDocTitle}_`. | ||
| * Surround user input with underscores (`_`) to indicate variable input, for example, `hammer organization create --name "_My Organization_" --label "_my_organization_"`. | ||
| * Include the title of the guide in italics after linking to a different guide, for example `in _{ManagingHostsDocTitle}_`. |
There was a problem hiding this comment.
Is this still true after DITA?
There was a problem hiding this comment.
It won't be true after DITA but we don't have an alternative yet and the option of keeping existing link conventions for non-satellite and making them DITA-tooling compliant only for Satellite is still on the table.
Still, you're making a good point and it might be best to remove it. We can later add a new convention once we agree on it.
There was a problem hiding this comment.
I agree with removing this line because we currently to not go by it.
Co-authored-by: Maximilian Kolb <[email protected]>
aneta-petrova
removed
the
Needs tech review
What changes are you introducing?
Why are you introducing these changes? (Explanation, links to references, issues, etc.)
Follow up on #4281
Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)
N/A
Contributor checklists
Please cherry-pick my commits into: