markhoerth opened a new pull request, #11205:
URL: https://github.com/apache/gravitino/pull/11205
## Summary
Introduces `docs/STYLE.md` as the canonical documentation style guide for
Apache Gravitino and applies six accompanying rules as mechanical sweeps across
the docs tree. Each commit adds a rule and applies it; commits are easy to skim
individually.
The six rules:
1. Drop "currently" / "the current behavior" filler. Docs describe the
current state by default; the qualifier adds nothing.
2. No gerund-led headings. Prefer an imperative verb ("Use `simple`
authentication") or a noun phrase over the gerund form ("Using `simple`
authentication"). Gerunds acting as established nouns ("Troubleshooting",
"Logging configuration") are fine.
3. No repeated leading verb across consecutive bullets. When every bullet
starts with "Supports X" / "Supports Y", lift the verb into a shared lead-in or
vary the verbs.
4. Drop "you can / you need to / you should" scaffolding. The imperative is
shorter and matches engineering voice.
5. Sentence case at every heading level, with proper nouns and initialisms
preserved. (Replaces a hybrid "Title Case for H1/H2, sentence case for H3+"
rule.)
6. Avoid abstract-subject framings ("The goal of X is to Y", "It is
recommended that you Y").
The first commit applies four older mechanical patterns ("or just use the
X", "In order to", "can not", and a one-off operate/refer-to fix in index.md)
plus the new "Please refer to" → "Refer to" sweep.
## Commits in this PR
```
cbf97e287 docs: global sweep for STYLE.md mechanical fixes
c7d053ca6 docs: codify 'currently' rule and sweep filler across all docs
e82cb26fc docs: codify no-gerund-headings rule and sweep across all docs
0d0f1ad56 chore: add vim swap file patterns to .gitignore
c4420bc06 docs: sweep 'Please refer to' -> 'Refer to' across all docs
c9cf557a1 docs: codify and sweep three style rules
80a71ea34 docs: switch to sentence case at every heading level
47bd6324d docs: codify and apply weak-voice / abstract-subject rule
```
## Scope
- Adds `docs/STYLE.md` (new file).
- Touches roughly ~100 docs files across `docs/` and its subdirectories.
Each individual change is mechanical and easy to skim.
- One small `.gitignore` update for vim swap files.
## Risk
Low. All changes are programmatic application of declarative rules.
Reviewers can focus on `docs/STYLE.md` and trust the rest as pattern
application.
## Follow-up
A second PR (`docs/polish-prose`) is ready on the same fork with per-file
prose rewrites that depend on these style rules being in place. It will open
after this one merges.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
