BathAfrica:Documentation authoring: Difference between revisions
BathAfrica (talk | contribs) Record completed SVG rendering and template branding |
BathAfrica (talk | contribs) Document OpenSite chapter, lesson, illustration and evidence conventions |
||
| (One intermediate revision by the same user not shown) | |||
| Line 24: | Line 24: | ||
The uploaded Cursor documentation contains 27 article sources and four template authoring guides. Those guides were not executable rendering templates. The shared templates above implement their fields. | The uploaded Cursor documentation contains 27 article sources and four template authoring guides. Those guides were not executable rendering templates. The shared templates above implement their fields. | ||
The | The 27 articles are now published under [[OpenSite/Reference]] and [[OpenSite/Guides]], using the shared BathAfrica templates. They were reconciled against implementation at development commit 77c3fee13944bcc4b5d487c77eb1f82fbe4c6ea7 (Phase 13C). Obsolete GUI, expressions, persistence, console and toolchain claims were corrected. Pages explicitly state that application tests were not rerun for this publication and that this is development documentation, not a commercial release. Keep those source-snapshot limits when updating the articles. | ||
Use product subpage titles such as OpenSite/Getting started and SiteMaster/Getting started. Keep verified functionality separate from planned features. Record the tested version and reproducible evidence when claiming verification. | Use product subpage titles such as OpenSite/Getting started and SiteMaster/Getting started. Keep verified functionality separate from planned features. Record the tested version and reproducible evidence when claiming verification. | ||
== OpenSite chapter and lesson structure == | |||
The OpenSite section now contains 58 content pages, including 17 guides, arranged in seven chapters: Start here; Documents and data; Materials; Python; Workspace and preferences; Reference and examples; Extend OpenSite. Start at [[OpenSite]]. Keep reference titles stable and link practical tasks to their exact references. | |||
Use [[Template:OpenSite scope]] for the compact version banner and [[Template:OpenSite lesson]] for new task lessons. It wraps the shared BathAfrica Tutorial fields: prerequisites, numbered steps, expected result and limitations. Use imported [[Template:Code]], [[Template:MenuCommand]], [[Template:Button]], [[Template:Caption]] and [[Template:Docnav]] where appropriate. Code examples should state their host, explicit units and clean-state assumptions and include a checkable result. | |||
The supplied Cursor examples were rewritten into 13 teaching scripts. Six explanatory SVG diagrams are labelled as diagrams, not application screenshots. Add genuine desktop screenshots only from a matching running build. The current site review checked links, template expansion, diagrams and navigation; it did not rerun OpenSite desktop or CTest tests. Keep [[OpenSite/Documentation status]] current when the implementation baseline changes. | |||
OpenSite chapter menus and breadcrumbs are maintained in the marked OpenSite block of [[MediaWiki:Common.js]]; scoped layout rules are in [[MediaWiki:Common.css]]. Preserve unrelated content when updating either page. New chapter entries must point to existing pages; avoid duplicate sidebar entries and self-referential previous/next links. | |||
Latest revision as of 14:17, 29 October 2026
This guide is for documentation authors across BathAfrica products.
Shared page templates
- Template:BathAfrica Command — command identifiers, examples, output, errors, limitations, and verification evidence.
- Template:BathAfrica Feature — behavior, source-reported status, units, hosts, licensing, and evidence.
- Template:BathAfrica Tutorial — prerequisites, steps, expected result, and limitations.
- Template:BathAfrica Workbench — tools, commands, and limitations.
- BathAfrica:Template examples — fictional rendering demonstrations.
Use the optional review parameter to display a review notice. A historical “verified” label is not evidence that the current build was tested.
Inline formatting
- Keyboard key: Ctrl
- Button label:
- Menu path: File → Save
See Template:BathAfrica Key, Template:BathAfrica Button, and Template:BathAfrica Menu for usage.
Existing SiteMasterDoc template migration
All 75 existing source templates and their 150 historical revisions have now been imported. Shared compatibility styles and extension fallbacks are installed. See BathAfrica:Template migration for the complete status and BathAfrica:Legacy template tests for the rendering gallery.
All 159 static dependency images have been recovered and preserved, including 155 recovered upstream because they were absent from SiteMasterDoc. All 159 are now installed and registered on this wiki. See BathAfrica:Image migration tests for the complete image gallery. All 159 images render after enabling native SVG rendering with a 256 KB size limit. The current imported templates use BathAfrica branding; original source histories and attribution are retained.
OpenSite source review
The uploaded Cursor documentation contains 27 article sources and four template authoring guides. Those guides were not executable rendering templates. The shared templates above implement their fields.
The 27 articles are now published under OpenSite/Reference and OpenSite/Guides, using the shared BathAfrica templates. They were reconciled against implementation at development commit 77c3fee13944bcc4b5d487c77eb1f82fbe4c6ea7 (Phase 13C). Obsolete GUI, expressions, persistence, console and toolchain claims were corrected. Pages explicitly state that application tests were not rerun for this publication and that this is development documentation, not a commercial release. Keep those source-snapshot limits when updating the articles.
Use product subpage titles such as OpenSite/Getting started and SiteMaster/Getting started. Keep verified functionality separate from planned features. Record the tested version and reproducible evidence when claiming verification.
OpenSite chapter and lesson structure
The OpenSite section now contains 58 content pages, including 17 guides, arranged in seven chapters: Start here; Documents and data; Materials; Python; Workspace and preferences; Reference and examples; Extend OpenSite. Start at OpenSite. Keep reference titles stable and link practical tasks to their exact references.
Use Template:OpenSite scope for the compact version banner and Template:OpenSite lesson for new task lessons. It wraps the shared BathAfrica Tutorial fields: prerequisites, numbered steps, expected result and limitations. Use imported Template:Code, Template:MenuCommand, Template:Button, Template:Caption and Template:Docnav where appropriate. Code examples should state their host, explicit units and clean-state assumptions and include a checkable result.
The supplied Cursor examples were rewritten into 13 teaching scripts. Six explanatory SVG diagrams are labelled as diagrams, not application screenshots. Add genuine desktop screenshots only from a matching running build. The current site review checked links, template expansion, diagrams and navigation; it did not rerun OpenSite desktop or CTest tests. Keep OpenSite/Documentation status current when the implementation baseline changes.
OpenSite chapter menus and breadcrumbs are maintained in the marked OpenSite block of MediaWiki:Common.js; scoped layout rules are in MediaWiki:Common.css. Preserve unrelated content when updating either page. New chapter entries must point to existing pages; avoid duplicate sidebar entries and self-referential previous/next links.