{"slug": "show-hn-ste-code-a-distillation-and-adaptation-of-asd-ste100-for-code", "title": "Show HN: STE-Code a distillation and adaptation of ASD-STE100 for code", "summary": "STE-Code, a documentation standard adapted from ASD-STE100 Issue 9, achieves a 96.6% pass rate on 59 documentation tests, compared to 11.9% for a plain assistant, a +84.7% improvement. The standard provides 51 writing rules, 4 grammar recommendations, a controlled vocabulary, and system prompt templates at five levels to remove ambiguity from code documentation. It is available on GitHub under the repository NikolaRHristov/STE-Code.", "body_md": "STE-Code is a documentation standard adapted from [ASD-STE100 Issue 9](https://asd-ste100.org) for code documentation. It gives you 51 writing rules, 4 grammar recommendations, a controlled vocabulary, and system prompt templates at five levels. The standard removes ambiguity, jargon, and hedging from README files, API documentation, docstrings, commit messages, and error messages.\n\nChoose the level that fits your token budget:\n\n| Level | File | Tokens | Best For |\n|---|---|---|---|\n1 |\n`level1/system-prompt.txt` |\n\n**2**`level2/system-prompt.txt`\n\n**3**`level3/system-prompt.txt`\n\n**4**`level4/system-prompt.txt`\n\nLevel 5 (the full specification) has 51 rule summaries at [ ste-code/artifacts/level5/](/NikolaRHristov/STE-Code/blob/Current/ste-code/artifacts/level5).\n\nCopy a system prompt into your LLM. The model writes clear, unambiguous documentation.\n\n```\nYou: Copy level1/system-prompt.txt into the system prompt field.\nLLM: You are an STE-Code technical writer. Apply these rules...\nYou: Check this docstring.\n     /** This function basically handles user stuff. */\nLLM: /** Creates a user or updates the data of a user. */\n```\n\nThe LLM applies the controlled vocabulary, the synonym table, and the sentence-length limits. It replaces jargon with approved words. It uses active voice and imperative mood.\n\nThe 51 rules cover nine sections:\n\n| Section | Rules | Covers |\n|---|---|---|\n| 1 — Words | 14 | Approved vocabulary, parts of speech, technical nouns and verbs |\n| 2 — Noun Phrases | 2 | Article use, noun clusters |\n| 3 — Verbs | 7 | Tense, voice, mood, verb forms |\n| 4 — Sentences | 5 | Length, clarity, contractions, completeness |\n| 5 — Procedures | 5 | Instructional writing, step structure |\n| 6 — Descriptions | 5 | Descriptive writing, comparisons |\n| 7 — Warnings | 3 | BREAKING, DEPRECATED, NOTE formatting |\n| 8 — Punctuation | 6 | Commas, hyphens, parentheses, lists |\n| 9 — Document Structure | 4 | Headings, lists, tables, organization |\n\nEach rule has a code-domain adaptation with paradigm-specific guidance for object-oriented, functional, procedural, declarative, and systems programming. The full rules are in [ ste-code/adapted/](/NikolaRHristov/STE-Code/blob/Current/ste-code/adapted).\n\nSTE-Code against a plain assistant on 59 documentation tests across 14 categories:\n\n| STE-Code | Plain Assistant | Improvement | |\n|---|---|---|---|\n| Pass rate | 96.6% | 11.9% | +84.7% |\n| Average score | 0.919 | 0.471 | +0.448 |\n\nTop categories: comments, error messages, and config files.\n\n```\nSTE-Code/\n├── README.md\n├── ste-code/\n│   ├── artifacts/\n│   │   ├── level1/system-prompt.txt     ★ ~1.2K tokens\n│   │   ├── level2/system-prompt.txt     ★ ~4.5K tokens\n│   │   ├── level3/system-prompt.txt     ★ ~8K tokens\n│   │   ├── level4/system-prompt.txt     ★ ~45K tokens\n│   │   └── level5/                      ★ 51 rule summaries\n│   ├── adapted/               The standard (57 adapted files)\n│   ├── data/                  Structured JSON (vocabulary, synonyms)\n│   ├── templates/             Additional system prompts\n│   ├── merged/                master.md (full spec consolidation)\n│   ├── refined/               Stage 2 — formatted extraction\n│   └── extracted/             Stage 1 — raw extraction\n├── spec/                      ASD-STE100 Issue 9 source (434 pages)\n├── translations/              Translation scaffolding (9 locales)\n└── .agents/                   Pipeline orchestration (agents, skills, config)\n    ├── config/agents.yaml     Agent backend configuration\n    └── tools/                 Assembly scripts (agent-agnostic)\n```\n\nAll assembly scripts use the agent runner at `.agents/tools/agent-runner.py`\n\n. The default backend is Hermes. Add other agents in `.agents/config/agents.yaml`\n\n.\n\n```\n# Assemble prompts (default: Hermes)\npython3 .agents/tools/assemble-level3.py\npython3 .agents/tools/assemble-level2.py\npython3 .agents/tools/assemble-level1.py\n\n# Use a different agent\npython3 .agents/tools/assemble-level1.py --agent claude\n\n# List available agents\npython3 .agents/tools/agent-runner.py --list\n```\n\nFor full documentation, see [ .agents/AGENTS.md](/NikolaRHristov/STE-Code/blob/Current/.agents/AGENTS.md).\n\nThe standard was built from ASD-STE100 Issue 9 through a five-stage automated pipeline:\n\n```\nExtract → Refine → Merge → Adapt → Artifacts\n(434pp)   (109f)    (1f)    (57f)    (5 levels)\n```\n\nNine specialized agents orchestrated 109 parallel workers. The adaptation replaced aerospace terms with code-domain equivalents.\n\nMIT. See [LICENSE](/NikolaRHristov/STE-Code/blob/Current/LICENSE).\n\n```\n@misc{ste-code-2025,\n  title        = {{STE-Code}: Simplified Technical English for Code Documentation},\n  author       = {{Nikola Hristov}},\n  year         = {2025},\n  howpublished = {\\url{https://github.com/NikolaRHristov/STE-Code}},\n  note         = {Adapted from ASD-STE100 Issue 9 (January 2025)}\n}\n```\n\nSTE-Code stands on decades of controlled-language research, documentation theory, and verification tooling.\n\n-\n**ASD-STE100 Simplified Technical English, Issue 9 (January 2025)**— the foundational standard STE-Code adapts to the code domain. Owned by** ASD — Aerospace, Security and Defence Industries Association of Europe**, Brussels; maintained by the** Simplified Technical English Maintenance Group (STEMG)**. Copyright and trademark of ASD.[https://www.asd-ste100.org/](https://www.asd-ste100.org/) -\n**AECMA / AIA Simplified English lineage**— STE's origin: developed in the late 1970s–1980s by the** European Association of Aerospace Industries (AECMA, now ASD)**with the** Aerospace Industries Association of America (AIA)**, at the request of the** Association of European Airlines (AEA)**. Working group founded 30 June 1983, Amsterdam; first Guide release 1986; became ASD-STE100 specification in 2005 and an international standard in 2025. Historical basis for STE-Code's core principle: enforceability determines survival (Caterpillar Fundamental English, unenforced, died 1982).\n\n-\n**Tobias Kuhn**—*A Survey and Classification of Controlled Natural Languages*(Computational Linguistics, 2014; 636+ citations). Source of the PENS classification (Precision, Expressiveness, Naturalness, Simplicity) used to profile STE-Code rules.[https://aclanthology.org/J14-1005.pdf](https://aclanthology.org/J14-1005.pdf) -\n**Norbert E. Fuchs & Rolf Schwitter**(University of Zurich) —*Attempto Controlled English (ACE)*(1996). Precedent for machine-processable controlled English and explicit quoting conventions for the use–mention distinction.[https://attempto.ifi.uzh.ch/](https://attempto.ifi.uzh.ch/) -\n**Rimay CNL research**—*On systematically building a controlled natural language for functional requirements*(PubMed). Source of the coverage methodology (88% of 460 real statements expressible).[https://pubmed.ncbi.nlm.nih.gov/34776756/](https://pubmed.ncbi.nlm.nih.gov/34776756/)\n\n**John M. Carroll**—*Minimalism*tradition in technical documentation (ACM SIGDOC). Learning-theoretic basis for register stratification: users act first and read at the moment of need.[https://dl.acm.org/doi/10.1145/296336.296362](https://dl.acm.org/doi/10.1145/296336.296362)\n\n**asciidoctest**(PyPI) —*Verifiable, stateful, and interactive documentation with AsciiDoc*. Reference implementation for code-block verification.[https://libraries.io/pypi/asciidoctest](https://libraries.io/pypi/asciidoctest)\n\n**Google Style Guides**— precedent for public, per-language style standards.[https://google.github.io/styleguide/](https://google.github.io/styleguide/)**Kristories/awesome-guidelines**— community catalogue of coding standards.[https://github.com/Kristories/awesome-guidelines](https://github.com/Kristories/awesome-guidelines)**github/codeql-coding-standards**— precedent for machine-enforceable standards as executable queries.[https://github.com/github/codeql-coding-standards](https://github.com/github/codeql-coding-standards)\n\nASD-STE100 is a copyright and trademark of ASD, Brussels. STE-Code adapts\nits *principles and rule categories* to the software domain; it does not\nreproduce the standard's dictionary or rule text. Users requiring the\nauthoritative aerospace standard should obtain Issue 9 directly from ASD\n(free of charge via the official form): [https://www.asd-ste100.org/](https://www.asd-ste100.org/).", "url": "https://wpnews.pro/news/show-hn-ste-code-a-distillation-and-adaptation-of-asd-ste100-for-code", "canonical_source": "https://github.com/NikolaRHristov/STE-Code", "published_at": "2026-07-31 08:58:16+00:00", "updated_at": "2026-07-31 09:22:44.645778+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "large-language-models"], "entities": ["STE-Code", "ASD-STE100", "NikolaRHristov", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/show-hn-ste-code-a-distillation-and-adaptation-of-asd-ste100-for-code", "markdown": "https://wpnews.pro/news/show-hn-ste-code-a-distillation-and-adaptation-of-asd-ste100-for-code.md", "text": "https://wpnews.pro/news/show-hn-ste-code-a-distillation-and-adaptation-of-asd-ste100-for-code.txt", "jsonld": "https://wpnews.pro/news/show-hn-ste-code-a-distillation-and-adaptation-of-asd-ste100-for-code.jsonld"}}