docs: add Writing Style section to CONTRIBUTING.md - #487
Merged
Merged
Conversation
Captures the review guidance that recurs on documentation PRs: reader as subject, must for requirements, one idea per sentence, no parenthetical asides, and re-checking nearby limitations when a fact changes. Signed-off-by: Mike McKiernan <mmckiernan@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Contributor
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
Documentation preview |
mikemckiernan
marked this pull request as ready for review
September 4, 2026 18:52
mikemckiernan
deleted the
devin/1788531861-contributing-writing-style
branch
September 4, 2026 18:53
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Proposal (draft): adds a short Writing Style section to
CONTRIBUTING.mdso external contributors see the guidance at PR time instead of learning it from review comments.CONTRIBUTING.mdcurrently covers filenames, headings, Kubernetes object names, and console blocks, but not sentence-level style.Five rules, each with a before/after pair drawn from recent OpenShift review feedback:
Opened as a draft because this guidance is arguably broader than one repo; the same rules are being added to the NVIDIA tech-docs skill-library so they apply across repositories. Close this PR if the repo-local copy is not wanted.
Link to Devin session: https://nvidia-cloud.devinenterprise.com/sessions/3524e6e8ae8b4f9fb04c2d0efcf25841
Open in Devin Desktop: https://nvidia-cloud.devinenterprise.com/desktop/session/3524e6e8ae8b4f9fb04c2d0efcf25841?variant=devin
Requested by: @mikemckiernan