Context: we need a page that gathers all the macros in xwiki. More broadly, we need some “catalogue” pages, that list every doc page carrying a certain type of xobject (rendering macro, UIXP, etc.).
Question 1: What type should a “catalogue” page be?
(I’m not proposing a new type- catalogue, just think the name “catalogue” is intuitive for imagining the page.)
Option 1: Reference page (my preference)
It’s a regular documentation page with the DocumentationClass attached and type reference. The only special thing is the content field, a Live Data whose displayed columns depend on the XClass (e.g. title, location, description, Extension Id etc).
It lists everything that exists on the topic (e.g. all macros), which is the definition of a reference page.
The related section of each page points to its pair for the other target.
Location
A top-level page under the corresponding target + pinning in the navigation, e.g. documentation.xs.user.rendering-macros titled “All Bundled Macros for Users”, and documentation.xs.dev.rendering-macros titled “All Bundled Macros for Developers”. It would be pinned in the navigation probably right after “Base” topic page.
A catalogue documents nothing specific. It’s an organizational page that gathers info together.
Landing pages are created and managed by the doc manager (the type pages- e.g. How-tos, the target pages- e.g. User Documentation, and the product pages xs and extensions).
Location
The catalogue would be listed right after the type landing pages.
To me it makes more sense as a reference page (option 1), since a landing page is structural and this one still carries content about the macros in the “description” column and because it is closer to the definition of a reference page in diataxis. WYT?
Question 2: What other XCLasses are we missing from the DocApp for documenting pages?
Currently, we have in the Documentation Application XClasses for documenting:
As a rule, I think I’d simply propose to use a reference page under the explanation page that explains the concept in question. For example, we will document somewhere what is a (Rendering) Macro in XWiki, and that will be an explanation page. Then we could have a reference page below it (i.e. nested) that would list all macros. Same for UIXPs, etc.
The separation by target is more tricky and depends on the topic. For example for UIXP, they’re all for developers. For macros, indeed, we can have macros for users and macros for developers. The pages should be cross-linked probably (maybe using the Related section).
WDYT?
For these, I think we’ll find them as we progress. The troubleshooting type of pages is a good candidate indeed. For icons, I’m not sure what you mean. What does it mean to document an “icon”? IMO Icons should be grouped by Icon Set and have one page per icon set (we won’t have many though, since we have only 2 icon sets we support ATM).
I’m referring to the icon pages that already exist in the old documentation, under Front-end Resources > Icons, where each page (e.g. backward) maps an XWiki IconSet name to its name in each icon theme (Silk, Font Awesome,..) using the IconMappingClass. => So probably we’ll need to move and improve to the docapp the IconMappingClass.
Another idea: if we end up with more of these “catalogue” pages, we could add a new panel called “Indexes” (name open to suggestions) and place it under the target panel in xwiki.org. Each product and target would have its own hierarchy, depending on what exists there. For example:
xs.user > Indexes panel would list: Icons, all bundled macros for users
xs.dev > Indexes: all UIXPs, all troubleshooting pages
This way we provide more visibility to such pages. WDYT?
( Just realized this would be an index of indexes :)) )
ok I didn’t know about this xclass. From what I see the goal is not so much to have one page per icon (since we have no links to these pages), but more to have a LD listing all of them. I feel that it might look odd in the top level LDs to list all those icons as pages.
One solution is to consider these icon pages as internal pages and without them being doc pages, and they’d just be used by the LD in the doc page for the Icon Set. WDYT?
Sounds good. We would need to test how it looks visually. It may feel a bit weird to have this Index panel before the topics since you need to understand the topics before being interesting in these indexes. Maybe they could be below the topics instead.
+1 for keeping them as internal pages. I created them mostly to contain the info of one icon only in a maintainable way. I don’t think the info about a single icon is worth its own reference page.
,