Branch: refs/heads/okf-xdocker-doc-captures Home: https://github.com/xwiki/xwiki-dev-llm Commit: f11878ac4025ccf307873e94c5d56ef9580ad7fc https://github.com/xwiki/xwiki-dev-llm/commit/f11878ac4025ccf307873e94c5d56e... Author: Vincent Massol <[email protected]> Date: 2026-07-27 (Mon, 27 Jul 2026) Changed paths: M .claude-plugin/marketplace.json M kimi.plugin.json M opencode.jsonc M xwiki/.claude-plugin/plugin.json M xwiki/instructions/xwiki-org.md A xwiki/okf/conventions/documentation-mechanics.md M xwiki/okf/conventions/documentation.md M xwiki/okf/index.md M xwiki/skills/xwiki-doc-writing/SKILL.md M xwiki/skills/xwiki-rest-api/SKILL.md Log Message: ----------- [Misc] Capture the xwiki.org documentation learnings from the XDOCKER doc review Batch of 19 durable, generic learnings collected while refactoring the "Install XWiki using Docker" documentation tree on xwiki.org, deliberately held back until the work was finished and then captured in one pass. okf/conventions/documentation.md -- the authoring rules * Fix the Highlights definition, which was wrong. It said "short points to help readers quickly discover key information"; it is actually a two-level list of the most important CHILD pages (level 1 = link, level 2 = description), filled only when a page has many children and then only with a subset, since the automatic "More" table already lists them all. The wrong wording caused a real authoring mistake. Also document "More" (automatic, nothing to fill) and that Related is for NON-child pages, never links to its own page, and must be re-checked after a restructure. * Correct the `target` allowed value: `administrator`, not `admin`. Both property value lists are now taken from the class definition itself, which also settles that there is no `troubleshooting` type -- a troubleshooting page is an Explanation with level-3 Cause/Solution headings, matching the existing pages. * Add the title-case rule for page titles (missing from the Documentation Guide too, so worth adding upstream). * Add a "How much belongs on one page" section: a How-to is ONE procedure (one numbered list, no level-2 sections), alternative procedures are siblings under an Explanation hub, How-to is the parent of its Explanation except for hubs, and one fact lives on one page. * Complete the {{version}} macro: `since`/`before` take a comma-separated LIST, `product` is free text, how each renders, and the scoping rule that only product behaviour gets a badge -- plus the test for whether a version in prose is load-bearing at all. * Add the {{scm}} macro's two hard limits (no rendering inside {{code}}, no `anchor` parameter), which make the existing "use {{scm}}" rule not always achievable. * Add a "syntax traps that bite" section -- `image:` parsed as a resource scheme, `--` silently opening a strikethrough that runs to end of block, `##...##` not protecting URLs or dashes, bare URLs in headings, blank lines ending lists, and anchors only serializing alongside a queryString. All verified against rendered output. * Add navigation-order pinning: an unpinned node sorts children alphabetically by TITLE, so finishing a tree includes deciding its order; pin a node in full or not at all; the tree must not contradict the page. okf/conventions/documentation-mechanics.md (new) -- the storage side Keeps the authoring rules above readable while giving the mechanics a home that is not a skill: the three DocApp xobjects, how to read the doc-quality checker's real findings from its violation objects instead of guessing at the opaque red banner, where navigation pinning is actually stored (the parent space's WebPreferences page) and why it must be verified through the Document Tree service, and the hidden-fragment pattern behind the {{display}} macro. skills/xwiki-rest-api -- generic REST traps only * Reading properties as XML: `<value>` is not the first child of `<property>`, and the `objects` listing carries no values at all -- both return empty rather than failing, which reads as "the page has no such field". * Page discovery must enumerate by space prefix: `GET <space>/spaces` returns the space itself, the query endpoint rejects XWQL, and REST-created pages have an empty `parent`. * A `202` does not mean the write landed -- back-to-back writes to the same page can silently drop one, so every write needs a read-back assert. * `hidden` is settable as a plain form field on the page PUT. * Everything documentation-tree-specific stays out, behind a single pointer to the new OKF page. skills/xwiki-doc-writing * Align the two places that told authors to fill Highlights with the corrected rule, and add title case to the review checklist. Examples throughout are kept product-neutral so that nothing specific to the Docker documentation reads as a general documentation rule, and the two figures observed on a single tree are labelled as such rather than stated as limits. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> To unsubscribe from these emails, change your notification settings at https://github.com/xwiki/xwiki-dev-llm/settings/notifications