docs(incident-management): normalize structure and wording - #586
docs(incident-management): normalize structure and wording#586mattaereal wants to merge 9 commits into
Conversation
Add canonical Key Takeaways, contributor fact-checked roles, nested page maps, absolute internal links where chrome was touched, and ContributeFooter separators. Preserve procedure and checklist bodies.
Deploying frameworks with
|
| Latest commit: |
16d28f8
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://9e5596c8.frameworks-573.pages.dev |
| Branch Preview URL: | https://docs-normalize-incident-mana.frameworks-573.pages.dev |
Rewrite non-stub frontmatter descriptions into the acceptable length band (preferred 140–160). Stub pages exempt. No body or credit changes.
Rename Further Reading H2s to the exact title the updated #561 validator accepts; sentence-case a few common section headings.
Child pages missing a canonical further/related H2 failed the updated #561 validator. Add a minimal Further Reading block linking the framework overview.
Neutralize fence comments that look like headings, canonicalize overview page-map titles, clamp descriptions, demote excess H2s, and mark template pages with content-model exceptions.
frameworks-volunteer
left a comment
frameworks-volunteer
left a comment
There was a problem hiding this comment.
Model: z-ai/glm-5.2 Reasoning: medium Provider: openrouter
Review: changes requested
Blocking: ## Further Reading casing (30 instances)
The PR adds 30 instances of ## Further Reading (Title Case) across leaf pages. The style guide explicitly lists ## Further Reading as incorrect and ## Further reading (sentence case) as the required form:
|
## Further reading|## Further Reading,## Further Reading & Tools|
The overview page correctly uses ## Further reading but all 30 leaf pages use Title Case. Since the PR's stated goal is normalizing to canonical structure, these should all be ## Further reading.
Affected files: communication-strategies.mdx, incident-detection-and-response.mdx, lessons-learned.mdx, all incident-response-template/*.mdx (communications, contacts, incident-response-policy, overview, roles-and-staffing), all runbooks/*.mdx, all templates/*.mdx, and all playbooks/*.mdx.
Minor: three descriptions below preferred 140-char minimum
These are within the 120-170 acceptable band but below the 140-160 preferred range:
communication-strategies.mdx— 131 chars (truncated mid-sentence, ends with "notification templates")playbooks/hacked-drainer.mdx— 128 charsplaybooks/malware.mdx— 138 chars
Minor: non-link bullet in overview Further reading
overview.mdx Further reading has: - Nested playbooks and the IR template customization checklist — this is a plain text bullet with no link, which is unusual in a Further reading section. Consider making it a link or removing it.
Minor: "SEAL 911 Cert surfaces" link text
overview.mdx Related frameworks uses [SEAL 911 Cert surfaces](/certs/overview) — "Cert surfaces" is odd phrasing. Consider [SEAL Certifications](/certs/overview).
What looks good
- All internal links resolve (verified every cross-framework link)
- Overview page maps match
vocs.config.tssidebar children exactly - Key Takeaways are substantive, accurate to page content, and under ~40 words
- Contributor frontmatter preserved correctly (original authors kept, empty reviewed/fact-checked arrays added)
- No security issues: no secrets, no injection vectors, docs-only
- Relative links converted to absolute paths consistently
---separator added before<ContributeFooter />on all pages- Template content-model exceptions properly documented with JSX comments
## What this framework coversused correctly on nested overview pages (sentence case, matches content model)- No accidental procedure/checklist body rewrites
|
Model: Re-review: all prior feedback addressedReviewed commit
SecurityNo issues. Docs-only PR, no secrets/scripts/injection vectors. No generated QA
Verdict: looks good, prior blocking item resolved. Safe to merge once CI passes. |
3 participants
Scope
Normalize content chrome for
docs/pages/incident-management/**only (SEAL frameworks content model). No other frameworks.Why
Align Incident Management pages with canonical Key Takeaway format, contributor roles, nested overview page maps, footer separators, and absolute internal links—matching prior framework normalize PRs.
Content model applied
> 🔑 **Key Takeaway**:(colon outside bold) from existing page substancecontributorswithwrote/reviewed/fact-checked(preserve usernames; empty arrays OK)##---before<ContributeFooter />index.mdxChanges
Substantive security guidance changes
None. Procedures, checklists, runbook steps, and template bodies preserved.
Intentionally unchanged
index.mdxfiles.mailmapValidation
Dependencies
Depends on content-model direction from #561 by reference only (no hard merge block intended beyond develop base).
Reviewer focus
vocs.config.tssidebar children