Write Beskid Documentation

Use ASD-STE100 Simplified Technical English, Issue 9, January 2025, for technical prose. Read the official ASD-STE100 site when you need the standard or its dictionary.

Orientation

Identify the document audience and the information authority before you write. Keep normative requirements, current procedures, learning material, and dated news in their separate sources.

Choose the correct source

Put normative requirements in openspec/specs/. Put public technical guidance in site/website/src/content/docs/docs/. Put learning material in the Book. Put dated news in the blog.

Do not write the same technical rule in more than one place. Link to the canonical page.

Write clear instructions

Use short sentences. Use active voice and present tense. Give one action in each step. Define each Beskid-specific term before you use it. Use the same term throughout the page.

Keep code, commands, paths, URLs, and identifiers unchanged. Do not change a requirement statement or a GIVEN/WHEN/THEN scenario only to change its style.

Check the page

Check that the title states the task. Check that links work. Run pnpm review:ste from site/website. Review each candidate manually. Use the documented, reasoned exception syntax only when the prose must stay unchanged.

Run the website tests and build for Docs changes. Run OpenSpec validation for normative changes. The STE review tool gives authoring evidence; it does not certify compliance.

The repository skill at .claude/skills/ste-100-technical-documentation/SKILL.md gives the same working rules to coding agents. It helps with authoring. It does not certify compliance.

Limits

This guide explains the repository authoring policy. The ASD-STE100 publication and the Beskid Standard remain authoritative. The advisory review finds candidates, but a contributor must make the final review decision.

Next steps

Use the ASD-STE100 guide for controlled-language checks. Use Standard changes when the change affects normative behavior.