Branch: refs/heads/master Home: https://github.com/xwiki/xwiki-dev-llm Commit: 80541f592d884e1673f4faca65d748956af98e85 https://github.com/xwiki/xwiki-dev-llm/commit/80541f592d884e1673f4faca65d748... Author: Vincent Massol <[email protected]> Date: 2026-09-04 (Fri, 04 Sep 2026) Changed paths: M xwiki/okf/conventions/documentation.md M xwiki/skills/xwiki-doc-writing/SKILL.md M xwiki/skills/xwiki-doc-writing/tools/README.md M xwiki/skills/xwiki-doc-writing/tools/docpages.py Log Message: ----------- [Misc] Close the Reference/table blind spot in the doc rules The guide's Reference clause is two-sided — "prefer tables … use code examples for API references" — and the second half reads as licence to drop the first until you notice that a bare signature is a table *column*, not an example: parameters, types, defaults and return value are exactly what a row holds. Nothing caught it, so a seven-member API reference shipped as seven headings each holding one signature, while its sibling written the same week used a table. * The OKF Reference rule now says so explicitly, names the two prose shapes that hide a table (a section per member; a `name: meaning` bullet list) and states the one exemption — every section carrying something no cell can hold, such as a screenshot per option * `docpages.py lint` grows two advisory rules for those two shapes. `{{code}}` deliberately does not exempt the first: a page of bare signatures is the defect, not the cure. Measured over 116 pages / 26 References in 8 harvested trees: 2 hits, both real, no false positive — a Reference with one screenshot per section was the false positive that made the image/diagram exemption necessary * The review checklist grows a "Shows — Reference" item, and says to apply it even to a page whose facts are all correct: the observed miss was a review that pronounced the page "complete and correct" and never asked about its shape * A new authoring step 7 carries the same rule for writing, and `tools/README.md` records both rules with their exemption Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Commit: a90de3c48acdc8bae8c232837feb88306992788a https://github.com/xwiki/xwiki-dev-llm/commit/a90de3c48acdc8bae8c232837feb88... Author: Vincent Massol <[email protected]> Date: 2026-09-04 (Fri, 04 Sep 2026) Changed paths: M xwiki/okf/conventions/documentation.md M xwiki/skills/xwiki-doc-writing/SKILL.md M xwiki/skills/xwiki-doc-writing/tools/README.md M xwiki/skills/xwiki-doc-writing/tools/docpages.py Log Message: ----------- Merge pull request #112 from xwiki/doc-linter-reference-tables [Misc] Close the Reference/table blind spot in the doc rules Compare: https://github.com/xwiki/xwiki-dev-llm/compare/a243a63f6c04...a90de3c48acd To unsubscribe from these emails, change your notification settings at https://github.com/xwiki/xwiki-dev-llm/settings/notifications