Fence the Human-Owned Paragraphs: A Markdown Contract for Model-Assisted Docs
The cheapest control you can put on a documentation generator is not a stricter prompt. It is a file format that gives the model no legal place to write except the prose blocks you hand it. This post defines three block classes in Markdown, a linter that fails on structural drift, and a splice step that can only rewrite the blocks it was granted. When a model tries to "improve" the deprecation…
Human-authored paragraphs must be fenced to prevent a model from rewriting them in a documentation generator. This approach helps maintain the integrity of human-written content by assigning specific write permissions to different block classes within Markdown files. The three block classes are:
1. Facts: Contains factual information such as configuration keys, script-generated content, and routing tables. Only a script reading the repository or build output can modify this block.
2. Prose: Includes human-authored content like motivation, tutorial steps, examples, and comparisons. A named person is responsible for any changes within this block, and any model-authored change will fail the build.
3. Deprecations: Contains deprecation warnings, security caveats, migration orders, and cost warnings. Only a named person may edit this block, and any model-authored change will also fail the build.
Each block is fenced using a consistent syntax with an 'owner' attribute (human, prose, or facts) and a unique 'id'. These fences prevent any model from writing outside the allowed blocks, and a linter ensures structural integrity during pull requests. By enforcing these block classes and write permissions, the documentation generator maintains the correct balance between model assistance and human oversight.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
