Add documentation review checklist page #5484
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| A focused review depends on having the right context up front. Skim these before opening the diff: | ||
|
|
||
| - The original issue, ticket, or PR description to understand the intent of the change. | ||
| - The page or section the change affects, in its currently-published form. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Hyphens] 'currently-published' doesn't need a hyphen.
| A focused review depends on having the right context up front. Skim these before opening the diff: | ||
|
|
||
| - The original issue, ticket, or PR description to understand the intent of the change. | ||
| - The page or section the change affects, in its currently-published form. |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'currently' that become outdated
| </Step> | ||
| <Step title="Voice and tone"> | ||
| - The tone matches the rest of the docs site. A reference page is concise; a tutorial is patient. | ||
| - Sentences are active and direct. Replace "It is recommended that you..." with "Use..." or "Set...". |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'it's' instead of 'It is'.
| - The page has a clear `title` and `description` in its frontmatter. | ||
| - Headings form a logical outline (`##` for major sections, `###` for sub-sections). | ||
| - No heading is skipped (don't jump from `##` to `####`). | ||
| - The first paragraph answers "what is this page about and why should I care?" without forcing a scroll. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'what's' instead of 'what is'.
| - The page has a clear `title` and `description` in its frontmatter. | ||
| - Headings form a logical outline (`##` for major sections, `###` for sub-sections). | ||
| - No heading is skipped (don't jump from `##` to `####`). | ||
| - The first paragraph answers "what is this page about and why should I care?" without forcing a scroll. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.FirstPerson] Use first person (such as ' I') sparingly.
| Review checks for code samples: | ||
|
|
||
| - **Runnable as-is.** A reader who copies the snippet, sets the documented environment variables, and runs it should get the documented result. | ||
| - **Idiomatic for the language.** TypeScript samples use `async/await`, not raw `.then()` chains. Python samples follow PEP 8. Shell samples use POSIX-compatible syntax unless Bash is required. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'PEP' has no definition.
| Review checks for code samples: | ||
|
|
||
| - **Runnable as-is.** A reader who copies the snippet, sets the documented environment variables, and runs it should get the documented result. | ||
| - **Idiomatic for the language.** TypeScript samples use `async/await`, not raw `.then()` chains. Python samples follow PEP 8. Shell samples use POSIX-compatible syntax unless Bash is required. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'POSIX' has no definition.
| Modern docs sites are increasingly read through search and through AI assistants that ingest the page as context. | ||
|
|
||
| - The page's headings are self-explanatory when read in isolation (as they will be in search results). | ||
| - The page's `description` reads naturally — it will be quoted by AI assistants when summarizing the page. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'naturally' if it's not important to the meaning of the statement.
| - **Approve with comments** for style preferences, minor wording suggestions, or follow-up improvements that don't block publishing. | ||
| - **Approve without comments** when the change is small, low-risk, and the author has already addressed prior feedback. | ||
|
|
||
| The goal of review is to ship correct, useful docs — not to round-trip every edge case. Trust the author to take comments seriously, and save formal change-requests for the things that actually block publishing. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'seriously' if it's not important to the meaning of the statement.
|
🌿 Preview your docs: https://fern-preview-fern-test-page-addition-1778624337.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
|
Requested by: Unknown |
Summary
Adds a substantial new page
Documentation review checklistunder the (already hidden) Resources section in the Docs product. The new page covers content quality, structure and navigation, code samples, accessibility, frontmatter/metadata, search/AI considerations, and review etiquette.This is a test change. The page is placed under the existing
hidden: trueResources section so it does not appear in the public sidebar; it is reachable only by direct URL for preview/review purposes.Changes
fern/products/docs/pages/resources/documentation-review-checklist.mdxfern/products/docs/docs.ymlunder the Resources sectionValidation
titleanddescription.fern checkwas not run because the CLI is not available in this environment; navigation was checked manually.Requested by: Fern Support