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.
By “internal” pages do you mean to have them hidden, but still move them in the new documentation, or to have them created outside the “Documentation” (or “documentation”) space? (If we don’t need them in the doc I wouldn’t move them, maybe they could be the only pages remaining under the previous doc, marked as hidden). WYT?
Anyway, I agree with having in the new doc just a page that displays the mapping in a LD.
Thanks!
Yes I meant keeping them as hidden. If that’s alright for now, we can leave them where they are. We’ll just have to remember to move them when eventually we decide to retire completely the previous doc devguide.
Yes, it is agreed in some forum post already that the pages from rendering.xwiki.org will be moved to the new doc. I’ll need to find it. However, I don’t think there are many user pages in it.
→ for users I’m not sure we do (yet). For developers most probably indeed. Thanks!
Icons: no per-icon documentation pages. The existing icon pages stay hidden, and the new doc gets a single page displaying the mapping in a Live Data.
An improvement was opened for an XClass for troubleshooting pages: DA-97.
Still open: an index page that lists all the catalogue pages and would sit in the navigation panel. This will be discussed in another thread / tested first.
Note that the location at https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/rendering-macros/ is still not good (see the discussion we had on #xwiki) and will require renaming all pages, since we’ll need to have a top level Rendering entry and move Rendering Macros under it. So the sooner the better to avoid either breaking readers or having to create redirects.
Note that we’re missing macros from Extensions, I think we need to add them as readers need to find them. Same for the other types. We probably need a column to indicate if each row is bundled in XS or comes from an Extension.
,