Content refactor#4
Merged
danieltoader-canonical merged 23 commits intoJun 18, 2026
Merged
Conversation
Heading Style:
- Change question-style headings to declarative, noun-phrase headings
(e.g., "How CVEs are rated") to match the Landscape Gold Standard.
Index Pages:
- Replace manual link lists with `{toctree}` directives
(`:titlesonly:`).
- Add introductory sentences before each toctree block.
- Remove `:hidden:` from toctree blocks to make the TOC visible.
Tone & Voice:
- Remove passive/weak constructions and colloquial phrases.
- Replace abbreviations (e.g., i.e., etc.) with "for example" or "such
as".
- Shift future tense ("will", "will be", "might") to present tense.
Links:
- Replace "here", "click here", and bare URLs with descriptive link
text.
Formatting:
- Apply inline code formatting for commands, file paths, and config
values
(snapd, uname -r, apt).
- Enforce consistent sentence case for headings.
- Remove trailing whitespace and trailing empty lines.
Structure:
- Add brief context sentences before lists and code blocks.
- Reorganize sections for better logical flow (explanation before
details).
- Extract supplementary content from paragraphs into bulleted lists.
- **Em dashes (`—`)**: Replaced all three instances with `--` (per `Custom.Emdash` error-level rule) - **Contractions**: Replaced `"doesn't"`, `"you're"`, `"we'll"`, `"you'd"`, `"don't"` with expanded forms throughout - **"e.g."** → `"for example"` (latinism avoidance) - **Pronouns**: Kept community-oriented "we"/"our" (acceptable per `vale.ini` config: `Custom.Pronouns = NO` for `[*.md]`) - **No "livepatching" or "livepatched"**: Compliant with `Custom.LivepatchVerbMisuse` error rule - **Descriptive links**: No "here" or "click here" link text anywhere - **No links in headings**: All headings are plain text
- Zero remaining pronouns (`we`, `us`, `our`, `you`, `your`, `I`, `me`, `my`) - Zero "here"/"click here" link patterns - Zero instances of "livepatching"/"livepatched" verb misuse - Zero em dashes - Zero repeating character separators - Zero boldface-with-colon patterns - Zero headings containing links or trailing punctuation - All "on-premise" instances corrected to "on-premises" - All `--` bullets converted to `*` - All YAML/MyST frontmatter, Sphinx directives, and code blocks preserved exactly
- Update meta descriptions for client, server, and overview pages - Replace collapsible release sections with plain headings - Simplify landing page toctree and remove explicit links - Add brief descriptions for client and server components
Replace the generic project overview with a product-focused description of Livepatch, its audience, and its documentation layout. Restructure the landing page to include the README directly, adopt the Diátaxis framework, surface release notes and contribution links, and add a comprehensive toctree that covers all documentation sections.
- Add blank lines after MyST anchors - Fix heading levels in patch management - Update URLs and custom wordlist entries
Removed unused table of contents section from release notes. Signed-off-by: Daniel Toader <daniel.toader@canonical.com>
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
2 participants
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.
refactor to resolve vale violations, and better conform with the Canonical writing styleguide, and Diátaxis