Proposal 23: Template for Documenting Rendering Macros
To ease the process of documenting rendering macros and ensure consistency, macro documentation pages must follow a predefined structure. The type of the page, according to Diataxis is of type Reference.
Proposed Structure for a Rendering Macro Reference Page
Description: A short and clear explanation of what the macro does, its purpose, and typical use cases.
Parameters: A standardized table listing all parameters with the following fixed column format: |=Name|=Mandatory|=Allowed Values|=Default Description
Name: name of the parameter
Mandatory: Yes/No
Allowed Values: accepted data types
Default: value used when none is specified
Description: what the parameter does and any relevant notes
Examples: Example/s using the Wiki Syntax must be included, showing realistic usage. Examples using the WYSIWYG editor could be included.
Note: This can be implemented either as a page template or using a class + sheet.
Page Titles for Rendering Macros and UIXPs
To avoid conflicts with existing page title rules (e.g., All how-to's and tutorials must start with a verb. (Doc guide-Page titles), pages that document structured information such as rendering macros and UIXPs, must follow dedicated rules. Therefore, page titles for rendering macro and UIXP documentation must use the following conventions:
Macro Pages: Page titles must contain quotes around the macro name and must include the word “macro”, e.g., "Display" macro.
This avoids ambiguity with how-to pages.
UIXP Pages: Page titles must contain quotes around the UIXP name and must include the word “UIXP”, e.g., “Add Application” UIXP.
This prevents confusion with how-to/tutorial titles (e.g., "Add application" UIXP vs. Add application as a how-to).
Note: Similarly, rendering macros and UIXPs often require page names that may already be taken, we need a generic rule for resolving naming conflicts when a contributor tries to create a page with an existing name in the same location.
Therefore, this is proposed:
Page Naming Conflict Guidelines
When you want to create a page but another page with the same name already exists in that location, follow these guidelines:
Add additional details to the name of one of the pages.
These details must not describe the page’s target or type, since that information is already included in the URL.
The additional details must not violate existing page-naming rules.
The proposal is to implement it using a Class/Sheet and introduce a UIXP in the docapp’s documentation sheet.
This is mostly for the WYSIWYG macro dialog but indeed, it could be interesting to document them (it’s more work though). I wonder if we have an example in the existing doc where we documented that.
Thanks for the info! I found some additional info here: Stable order for macro parameters. I’m wondering if advanced parameters can be documented in the Optional section. Since they are not displayed from the beginning, nor mandatory. And mentioning the details about their advanced nature in the description section?
I don’t feel it’s important to document most parameters, they only make sense for the WYSIWYG and reading them doesn’t bring much value IMO. For ex, what’s the interest to know that such param has order 3?
Advanced: Not really useful in the doc
Description: already there
DisplayHidden: maybe useful so that readers know why they won’t see the parameter displayed
DisplayType: already covered by the “allowed value” column
Feature: already covered by the “mandatory” column + “description”?
Group: already covered by the “mandatory” column
Hidden: feels too technical
Id: already covered by the param name column
Mandatory: already covered by the “mandatory” column
Name: only for WYSIWYG. Could be interesting since the property id is not displayed in the WTSIWYG UI AFAIK.
We don’t need a column for that, but we could ask documentation writers to put simple parameters before advanced ones. IMO it’s just common sense so I agree we don’t have to add anything.
Some features have a complex group/mandatory pattern. E.g. only one in the group has to be filled up for the macro to work as intended. I’m not sure it’d be good to describe it in the “mandatory” column (lot of repeated text). Note that this could be described with asterisks and a footnote. It will be useless on most simple macros so I agree to not add a column for it.
Overall I agree with this. The technical annotations can be documented on the generic macro doc for devs, and we can safely assume the devs can check the exact values themselves if that’s what they are looking for.
+1 for the structure proposed. I think the flexibility of a template would be better than using a class+sheet even if it’s worst for long-term maintanibility. Having a specific tag or badge on the templates or anything to make them easily filterable would be useful though
