Branch: refs/heads/doc-textual-content-uses-code-macro Home: https://github.com/xwiki/xwiki-dev-llm Commit: c8ad58356fe94fb4ac810cbc0e06b9365dc47ea9 https://github.com/xwiki/xwiki-dev-llm/commit/c8ad58356fe94fb4ac810cbc0e06b9... Author: Vincent Massol <[email protected]> Date: 2026-09-11 (Fri, 11 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/docpages.py Log Message: ----------- [Misc] Show textual content as a code macro, never as a screenshot of text * Add the rule to okf/conventions/documentation.md: the screenshot / code-macro choice follows what is being shown, not the page's audience. A screenshot is for a UI; anything that is itself text — a configuration file, a command, a log line, a query — gets a code macro, above all where the reader has to edit or copy it, since text cannot be selected out of an image. A picture of text is also unsearchable, untranslatable, invisible to a screen reader and impossible to diff when the shipped default changes. * Amend the two How-to step rules, which read as screenshot-only, and the frontmatter summary. * Mirror it in the xwiki-doc-writing skill: the result-step rule, the "give the page something to look at" step and a new review-checklist item. * Widen tools/docpages.py accordingly. It enforced one visual per audience (image for user/admin, code for developer), which rejected a correct administrator How-to whose steps show xwiki.properties as code. No check can tell a screenshot of a UI from a screenshot of text, so the linter now accepts either form and the choice between them is stated in the OKF as the writer's judgement; the audience still decides which one the message names. Found while documenting the Active Installs opt-out procedure, whose steps edit xwiki.properties and had been captured as two screenshots of that file. 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