Add automated style guide#4830
Conversation
github-actions
Bot
added
Needs tech review
|
It would be better to implement this as rules for writing rather than a validation check. |
aneta-petrova
removed
Needs tech review
Which part? (EDIT: Which part of the PR?) |
Actually, I might have misunderstood what you're trying to achieve with this PR. Not sure what that is. Consider my comment premature. |
aneta-petrova
force-pushed
the
ai-contributors
branch
4 times, most recently
from
41cc619 to
a569878
Compare
|
I'm not ready to switch this to |
aneta-petrova
force-pushed
the
ai-contributors
branch
from
881b9bb to
0609413
Compare
|
You could put all the AI guidelines into a single CLAUDE.md file. |
Thanks for the feedback regarding the addition of an AI instructions file! I agree there's real value in providing project-wide context for AI tools, but perhaps there's a fundamental difference in the audiences at play here. The style guide I'm proposing in this PR is intended for human eyes and writers. An AI configuration file like Right now, the repository already has excellent automation and contribution resources:
There's certainly value in using a root configuration AI file ( Introducing a repo-wide AI file is a great conversation to have, but given that it affects global repository configuration for all contributors and tools, it feels a bit out of scope for this specific PR. It would certainly be interesting to see how other contributors set up their |
CLAUDE.md files are extremely readable because they are in markdown. All the guidelines are in a single place, with sections and TOC. Our SMEs routinely check the OpenShift sandboxed containers CLAUDE.md file because it is a style guide and a repo guide all in one. It replaces contributors' guidelines and is easier to maintain because we tell Claude to update it. Our writers check their work against the CLAUDE.md file, in addition to the DITA and style Vale checks. |
aneta-petrova
force-pushed
the
ai-contributors
branch
2 times, most recently
from
3cd3a69 to
4829624
Compare
|
Ready for review now! :) I updated the PR's description to explain this proposal. I recommend reading both the 'what' and the 'why' parts because this is a big change with some reasoning behind it. As the last change before switching this to 'ready for review', I also tried to make the styling of the Contributors' guide as close to the styling of the regular guides as possible but I'm afraid there's only so much I can do due to the markdown vs asciidoc differences. |
|
Would you consider converting the resulting MarkDown file to AsciiDoc and using the standard build for HTML output? EDIT: Actually, AsciiDoctor has its own MD coverter in Ruby: https://github.com/asciidoctor/kramdown-asciidoc |
|
Thanks for the suggestion, @Lennonka! I can certainly try, I appreciate the hint on how to bring this closer to AsciiDoc. I'll investigate how it could work. |
aneta-petrova
force-pushed
the
ai-contributors
branch
2 times, most recently
from
e185863 to
cbd869a
Compare
Convert CONTRIBUTING.md to AI skills for contribution validation Add Contributors' Guide with markdown-based build system Make tweaks to Vale and AI skills structure Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
aneta-petrova
force-pushed
the
ai-contributors
branch
from
c9731a8 to
54d82e3
Compare
|
The Contributor's Guide is now built using The guide has the same build targets as any other guides (foreman-deb, foreman-el, katello, orcharhino, satellite, and the containerized builds) and that's intentional because I didn't want to make things more complex by adding a new, universal build target. The builds are all identical in content. For example: https://theforeman-foreman-documentation-preview-pr-4830.surge.sh/nightly/Contributing/index-katello.html Ready for another round of review :) |
4 participants
What changes are you introducing?
The main part of this PR is a new
doc-Contributingdirectory. This directory provides a new guide, Contributors' guide, which provides a human-friendly overview of all our contribution resources in a single place.It's a style guide that is automatically updated based on the latest state of our automation resources: Vale rules and AI skills.
In addition to the new guide, other changes include the following:
validate-contributionandpersonas.The new guide is a dedicated style guide for the Foreman Documentation project. It concatenates the following resources:
OverviewandExamplesget pulled into the style guide in full, and the rest (AI instructions) gets pulled in as collapsible content)Why are you introducing these changes? (Explanation, links to references, issues, etc.)
There are so many style resources and guidelines and rules that it's hard for a person to keep up with them. Automation should help us conform to all of these rules, but defining the rules both in a style guide and through automation introduces overhead and the risk of the style guides and automation getting out of sync.
With an automatically built style guide such as this one, we have one source of truth -- the automation-friendly resources -- but still keep a human-friendly guide for easy reference.
Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)
This project is based on the idea that if we want to introduce a new style/contribution rule, we should think in an "automation-first" rule. In its most radical sense, it would mean that if it can't be automated (through an AI skill or a Vale rule etc.), it should not be a contribution rule. And because not everyone's this radical, there's CONTRIBUTING.md for exceptions :)
One of the outcomes should be being able to show the automated style guide next to a regular style guide for comparison. It doesn't have to be a 1:1 match but just to show that the automated style guide can also serve as a style guide for a documentation project.
Contributor checklists
Please cherry-pick my commits into: