本文由 AI 分析生成
Summary
Contentsquare Engineering Blog’s 2023 walkthrough of adopting Vale — an open-source prose linter — to enforce writing standards in a Docs-as-Code workflow. The approach embeds writing quality feedback directly into engineers’ existing IDE and CI pipeline, making documentation contribution accessible without requiring engineers to read a style guide PDF.
Contentsquare 工程部落格 2023 年關於採用 Vale（開源文字 linter）在 Docs-as-Code 工作流程中執行寫作標準的介紹。這種方法將寫作品質反饋直接嵌入工程師現有的 IDE 和 CI 流水線，無需閱讀風格指南 PDF 即可參與文件貢獻。
Key Points
- Vale: open-source command-line prose linter; applies style rules as YAML config files; supports custom rule sets
- Docs-as-Code: documentation written in plain-text markup in IDE, tracked in version control, built via CI — engineers become first-class doc contributors
- Custom YAML rules: teams can encode their own style guide into Vale rules (e.g., preferred terminology, word choice, sentence length)
- IDE integration: VSCode Vale extension provides real-time lint feedback as engineers type — same developer loop as code linting
- CI integration: Vale runs on pull requests; writing violations block or warn like code style failures
- Engineer-to-writer ratio: typically 7:1 to 40:1; Docs-as-Code makes this ratio workable by bringing engineering tooling to writing
- Problem solved: style guides “in a humongous PDF read by nobody” replaced by actionable, inline feedback
Insights
The real insight here is treating prose quality as a software quality problem — addressable by the same tooling loop (lint → fix → CI gate) that engineers already use for code. Vale’s YAML-based rules lower the barrier to encoding institutional style decisions into automation. The “developer loop vs. writer loop” framing (attributed to Kelsey Hightower) is useful: when the two loops share the same toolchain, engineers stop viewing documentation as a foreign activity.
Connections
Raw Excerpt
It takes both the organization staff and engineer persona specifics into account by making engineers first-class contributors to documentation.