Description

• Problems to solve
• Proposals sent on the forum for review
  • Proposal: Improve usage of image macro
  • Proposal 1: Apply Diataxis
  • Proposal 2: Target Users
  • Proposal 3: Review status
  • Proposal 4: Documentation XClass
  • Proposal 5: Location of Documentation Pages
    • Option 1
    • Option 2
    • Common
  • Proposal 6: LiveDatas
  • Proposal 7: Navigation Tree
    • Option 1
    • Option 2
    • Option 3
      • Positioning Pages in the Nav Tree
    • Nav for Extensions
    • Other Navigation Improvements and Cleanup
  • Proposal 8: Landing Pages
    • Highlights Sections
      • Common Criteria
      • Specific Criteria for each Type of Landing Page
      • Format
      • Rules for Changing the Highlighted Pages
  • Proposal 9: Nav vs Menu
  • Proposal 10: Glossary
  • Proposal 11: Heading structure for Doc Pages
  • Proposal 12: Additional image styling rules
    • Gallery Macro
    • Image Placement
    • Adding clear visual guidance in screenshots
    • Image Names
      • Migration Strategy for Attachments Names
  • Proposal 13: Standardizing page names/titles
    • Page Titles
    • Page Names
    • Migration Strategy for Page Names
  • Proposal 14: Syntax for UI Elements
    • Option 1:
    • Option 2:
  • Proposal 15: Use Uppercase for XWiki Terminology
  • Proposal 16: The UI for the XProperties
    • Option 1
    • Option 2
  • Proposal 17: Reference pages and tables
  • Proposal 18: Captions for Attachments, Tables
  • Brainstorm: Standard Table Style
    • Option 1: Using the `figure` and `figureCaption` macros
    • Option 2: Using inline styling
  • Proposal 19: Perspective of the Documentation
    • Option 1
    • Option 2
  • Proposal 20: Introduce a  Macro for Marking Deprecated Content Inside Active Pages
  • Proposal 21: Add a “Documentation Resources” Section to the Documentation Guide
  • Proposal 22: When to Use Landing Pages
  • Proposal 23: Template for Documenting Rendering Macros
    • Proposed Structure for a Macro Reference Page
    • Page Titles
  • Additional Guidance for Proposal 13: Page Names
  • Proposal for search
  • Proposal 24: Change the splitting of documentation from Product > Target > Topic to Product > Topic > Target
    • Context
      • Advantages of having it this way
      • Disadvantages
    • Proposal: Have documentation split by topic and only then by target
      • Option 1
        • Advantages:
        • Disadvantages:
      • Option 2
        • Advantages:
        • Disadvantages:
      • Option 3
        • Idea 1: Mixing the pages in the navigation
          • Advantage:
          • Issues:
        • Idea 2: Use icons per targets
          • Advantages:
          • Issues:
        • Idea 3: Filter in a separate section of the panel the target
          • Advantages:
          • Issues:
        • Idea 4: Having a visual separation in the navigation based on some color codes.
          • Issues:
      • Option 4
        • Advantages:
        • Disadvantages:
• Proposals not yet sent on the forum
  • Proposal 25: Use Review Class for Documentation Quality and Validity
    • Proposed workflow
    • Additional Proposal: Work in Progress Visibility
  • Proposal 26: Moving the Documentation Guide from the Dev Wiki to the Main Wiki
    • Why?
    • What to do
  • Brainstorming: Gallery Macro vs. Image Macro
• Other
• Pages to rework about documentation
• Brainstormings not yet sent to the forum
• User Survey: Feedback on the New Documentation

Problems to solve

• Problem 1: Finding the right doc for the current reader (admin, user, or dev)
• Problem 2: Not always up to date
• Problem 3: Logical navigation structure of the doc
• Problem 4: Documentation split between xwiki.org and extensions sub-wiki

Proposals sent on the forum for review

Proposal: Improve usage of image macro

By adding a style parameter, see https://forum.xwiki.org/t/image-styling-for-xwiki-org/16925

Proposal 1: Apply Diataxis

https://diataxis.fr/ is a way of thinking and organizing the documentation. This proposal is about imagining how we could apply it, and more generally how to improve the documentation for xwiki.org.

In Diataxis, all documentation pages are of one of 4 types:

• Tutorials - learning-oriented experiences
• How-to guides - goal-oriented directions
• Reference - information-oriented technical description
• Explanation - understanding-oriented discussion

Example of mapping the current concepts of xwiki.org into these types:

• Our tutorials are of type tutorial but they often go beyond and add "Reference" and "Explanation" in them.
• Some FAQ entries are actually "howto guides", others "explanations", etc.
• Our Reference documentation often mixes Explanations
• Our snippets.xwiki.org pages are "howto guides"
• We may have some tutorials that are actually "howto guides"

We need to make sure that all our docs are of one of the 4 types and that they don't do more (they should link to other pages for other types). This includes extension docs. The consequence is that we'll have small and focused pageswith the following advantages:

• Simpler to read
• Less distracting
• Simpler to write
• Simpler to filter in LDs
• Simpler to review/update the review status

Proposal 2: Target Users

In addition to doc page types (diataxis), also differentiate the pages by target: users, admins, developers.

When presenting the target, always use this order (in the nav, in the page content, etc): User > Admin > Dev

Proposal 3: Review status

In order to track quality of each doc, for each doc page register when it's been last reviewed and by whom.

Proposal 4: Documentation XClass

Introduce a Documentation XClass with the following xproperties: 

• Type (Tutorial, Howto, Reference, Explanation)
• Target (User, Admin, Dev)
• Last Reviewed Date
• Last Reviewer

Proposal 5: Location of Documentation Pages

There are 2 main options:

• Option 1: Everything on e.x.o
• Option 2: Everything on the main wiki

Note that having documentation split on several wikis is not good because it prevents having a clean navigation and LD/LTs (as they don't work cross wikis and even if they worked, the merge would be too complex).

Option 1

• Create nested pages for the documentation of the extension (one page per target and type) 
• Remove the usage of the Description field and replace the TOC zone with a LD listing children pages
• Use the XS Standard Flavor as the tip of the documentation (when clicking on the "Documentation" menu link, you land there)
• Pros:
  • Single place for both extension metadata and extension documentation
• Cons:
  • Mixes technical content (extension metdata, deps, etc) with documentation, even if the doc pages are under nested pages
  • The user will see that they're on extensions.xwiki.org and in the header, the logo will be that of XWikiExtensions. It'll feel weird.
  • The breadcrumb for the doc will have the Extension name

Option 2

• Move all extension doc from exo to the main wiki. 
• For each extension we will have a page named the same as the exo page (landing page) and under which the various docs for that extension will be.
• Replace the Description field on exo by a Display macro, to display the content of the extension page on the main wiki
• Pros:
  • The navigation for the user will be seamless and no odd wiki name/logo will be displayed
• Cons:
  • Devs will need to import new extensions on exo and document them on the main wiki
  • The breadcrumb for the doc will have the Extension name
  • More reorg work since we'll need to move more documentation

Our preference goes to option 2 since we need to make it the best for readers even if it's a bit harder for doc writers.

We also want to separate the doc for XS from the doc for non-bundled-in-XS extensions:

• The doc for XS should be reached when clicking on the "Documentation" menu entry
• The doc for non-bundled-in-XS extensions should be reached when going to e.x.o.

In order to achieve this, we propose to:

• Introduce a new xproperty to the Doc XClass (see proposal 4) to mark if a doc page is for XS or for extensions non-bundled in XS (by adding a "bundled in xs" boolean xproperty)
• By default don't show non-XS doc in the main wiki
• By default don't show XS doc in exo (the LT/LD of extensions should filter out extensions bundled in XS by default)

Visually, the idea is to show if the current doc page concerns xs or a non-bundled-in-XS extension by adding the info on the line of the Likes and Tags, in the form of a pill. In the future, it would be nice to generalize the idea and have a pill with a link to the extension page on exo.

Common

Whatever option is chosen, the general idea is to move all docs under the concerned extensions:

• When a doc page content concerns several extensions, document it in the parent extension that depends on those extensions. 
• For example the "Edit a Page" how-to has 3 steps: 1) click on the Edit button, 2) Modify the content in the CKEditor UI and 3) Use the action bar to save or cancel. This means this how-to will be located at the level of the XS Flavor extension:

  ├─ XS Flavor Extension (user: howto: edit a page <- at this level as it uses several dependent extensions)
  ├─ ├─ Flamingo Skin Extension (user: edit buttons + the action bar with save/cancel/etc)
  ├─ ├─ WYSIWYG Extension (admin: selection of the default wysiwyg editor)
  ├─ ├─ Realtime WYSIWYG Extension (user: RT feature)
  ├─ ├─ CKEditor Extension (user: the editor based on CKEditor)

In addition the proposal is to fold all docs that are on commons.xwiki.org and rendering.xwiki.org into the XS documentation and to remove those wikis. They were there initially to try to promote commons/rendering independently of Platform/XS but that didn't work that well and for the reasons listed above, it's better for navigation if everything is in the same place.

Proposal 6: LiveDatas

Use LiveDatas at the following places:

• At the top level of the documentation provide a big LiveData table listing all doc pages, with filterable columns for type and target (and last reviewed probably too). 
• Use this LD in all landing pages (see below Proposal 8: Landing Pages) (user guide, dev guide, admin guide, etc). 
• Also use this LD in all doc pages for listing children pages. ((Even if XWiki offers the option to view a page's children as a LiveTable via the 'More Actions' → 'Children' menu, we felt that this is not sufficient for users. It’s more helpful for them to see the children listed directly on the page in a LiveTable))
  • Implementation note: Use a XSheet bound to the doc XClass to automatically add a section at the end of pages, entitled "Additional Topics"

Proposal 7: Navigation Tree

We propose that the main entry point for the documentation be a page called "Doc" (/Doc) (We would want to use "Documentation" but we can't since it's currently the location of the old documentation). This page would serve as the home of the documentation and include:

• a card pointing to the Documentation for XWiki Standard (/Doc/XS)
• a card pointing to Documentation for non-bundled extensions. (/Doc/Extensions)

Also, the main entry point would contain a LD listing all existing documentation pages, to filter pages across both sections.

Note: Keep in mind that when a feature is removed from the bundled ones or added to it, we would also need to move its documentation to the specific location accordingly.

To simplify the navigation panel, the Product and Target can be moved out as follows:

• Have two panels for navigation:
  • One for selecting a target, similar to the Quick Links Panel.
  • One for displaying the main navigation tree, that changes based on the target selected in the target panel.
    *The Product selection can be moved outside the navigation menu:
  • You select the documentation for a product directly from the horizontal navigation under the Documentation menu (the new documentation is temporarily placed in a submenu).

The main navigation tree in the wiki XS documentation:

Option 1

If the User target is selected from the first panel:

├─ XWiki Standard for Users
│  ├─ Getting Started
│  ├─ ├─ ..
│  ├─ ├─ ..
│  ├─ Page
│  ├─ ├─ Tutorials
│  ├─ ├─ Howtos
│  ├─ ├─ ├─ View a Page
│  ├─ ├─ ├─ ├─ Hide or Unhide a Page
│  ├─ ├─ ├─ ├─ Change the Syntax
│  ├─ ├─ ├─ ├─ View Page Children
│  ├─ ├─ ├─ View Page Comments
│  ├─ ├─ ├─ View Page Attachments
│  ├─ ├─ ├─ View Page History
│  ├─ ├─ ├─ View Page Information
│  ├─ ├─ ├─ ..
│  ├─ ├─ ├─ Edit a Page
│  ├─ ├─ ├─ ├─ Edit a Section
│  ├─ ├─ ├─ ├─ Edit a Page with the Wiki Editor
│  ├─ ├─ Explanations
│  ├─ ├─ ├─ Simple and Advanced Editing
│  ├─ ├─ ├─ Section Editing Limitations
│  ├─ ├─ References
│  ├─ ├─ ├─ Realtime Edit Actions
│  ├─ ├─ ├─ ├─ Common Edit Actions
│  ├─ ├─ ├─ Wiki Editor Toolbar
│  ├─ ├─ ├─ User actions available on a page
│  ├─ User
│  ├─ ├─ Howtos
│  ├─ ├─ ├─ ├─ Create a page by using the Add page action
│  ├─ ├─ ├─ ├─ Create a page by using a wanted link
│  ├─ ├─ ├─ ├─ Create a page by entering directly the URL of the new page
│  ├─ ├─ ├─ References
│  ├─ ├─ ├─ ├─ ...
│  ├─ ├─ ├─ Explanations
│  ├─ ├─ ├─ ├─ Creating: Simple vs. Advanced
│  ├─ Notifications
│  ├─ ├─ Howtos
│  ├─ ├─ ├─ ..
│  ├─ Like
│  ├─ ├─ Howtos
│  ├─ ├─ ├─ Like or Unlike a Page

If the Administrator target is selected from the first panel:

├─ XWiki Standard for Administrators
│  ├─ Getting Started
│  ├─ ├─ ..
│  ├─ ├─ ..
│  ├─ Administration
│  ├─ ├─ Tutorials
│  ├─ ├─ Howtos
│  ├─ ├─ ├─ Administer Your Wiki
│  ├─ ├─ ├─ Change Extension Rights
│  ├─ ├─ ├─ Change Extension Rights when Viewing a Page
│  ├─ Like
│  ├─ ├─ Howtos
│  ├─ ├─ ├─ Administer Like Preferences
│  ├─ Subject #3
│  ├─ ├─  Tutorials
│  ├─ ├─ ├─ ...

If the Developers target is selected from the first panel:

├─ XWiki Standard for Developers
│  ├─ Getting Started
│  ├─ ├─ ..
│  ├─ ├─ ..
│  ├─ Application creation
│  ├─ ├─ Tutorials
│  ├─ ├─ ├─  Creating a FAQ application
│  ├─ ├─ Howtos
│  ├─ ├─ ├─ ...
│  ├─ Yjs
│  ├─ ├─ Howtos
│  ├─ ├─ ├─ Configure WebSocket Collaboration with Yjs
│  ├─ ├─ References
│  ├─ ├─ ├─  Yjs WebSocket Endpoint
│  ├─ Subject #3
│  ├─ ├─ ...

Explanations:

• The Getting Started will display as children a chosen list of documentation pages that:
  • Are ordered logically and by usage priority.
  • Help people understand and use the platform in general, depending on their role (user/admin/dev).
  • Are maintained manually.
• By subject which is the feature/ extension name, then by type (see also https://diataxis.fr/complex-hierarchies/#two-dimensional-problems)
• Each tree node with children is a landing page with explanations, some highlighted docs accordingly, and a LD with content based on the Documentation XClass and filtered to match the target + type.
• We also plan to have the current page highlighted in the navigation tree, so users quickly see where they are in the documentation structure.
• Note: we can also have the 4 top level entries for the types (Tutorials, Howtos, Explanations and References), same as what is shown in option 3.

Pros:

• Nice navigation
• The useful doc pages from Getting started are easily accesed at top level
• Readers have context

Cons:

• Manual navigation, hard to maintain
• We have too many subjects (probably hundreds) and it'll be hard for users to navigate the tree to find a topic (we can onyly display like 15-20 entries at once in the tree)

Option 2

If the Users target is selected from the first panel:

├─ XWiki Standard for Users
|  ├─ Tutorials <-- landing page listing all user guide tutorials
│  ├─ ├─ List 5 tutorials to highlight
│  ├─ ├─ More...
│  ├─ How-to
│  ├─ ├─ Create a Page
│  ├─ ├─ Edit a Page
│  ├─ ├─ Edit Your Profile Information
│  ├─ ├─ More...
│  ├─ References
│  ├─ ├─ Realtime Edit Actions
│  ├─ ├─ More...
│  ├─ Explanations
│  ├─ ├─ Simple and Advanced Editing
│  ├─ ├─ More...

If the Administrators/Developers target is selected from the first panel:

├─ XWiki Standard for Administrators/Developers
|  ├─ Tutorials
│  ├─ ├─ List 5 tutorials to highlight
│  ├─ ├─ More...
│  ├─ How-to
│  ├─ ├─ ...
│  ├─ ├─ More...
│  ├─ References
│  ├─ ├─ More...
│  ├─ Explanations
│  ├─ ├─ More...

Explanations:

• Nav ordered by Type only (with some highlights)

Pros:

• Simple navigation
• Fixed tree size that can be open fully at all times
• No maintenance!

Cons:

• Readers will use the LDs to navigate (is it a problem?)
• Readers are disoriented, not knowing where they are in documentation
• Readers might not know whether they should look for a howto/ reference, they might just know the subject/ feature.

Option 3

If the Users target is selected from the first panel:

├─ XWiki Standard for Users
│  ├─ Getting Started
|  ├─ Tutorials
|  ├─ Howtos
|  ├─ Explanation
|  ├─ References
│  ├─ Page
|  ├─ ├─ View a Page
│  ├─ ├─ ├─ Hide or Unhide a Page
│  ├─ ├─ ├─ Change the Syntax
│  ├─ ├─ Edit a Page
│  ├─ ├─ ├─ Edit a Section
│  ├─ ├─ ├─ Edit a Page with the Wiki Editor
│  ├─ ├─ ├─ Hide or Unhide a Page when Editing
│  ├─ ├─ ├─ Change the Syntax when Editing
│  ├─ ├─ Simple and Advanced Editing
|  ├─ ├─ Section Editing Limitations
│  ├─ ├─ Hidden Pages
│  ├─ ├─ Syntax Conversion
│  ├─ ├─ Realtime Edit Actions
│  ├─ ├─ ├─ Common Edit Actions
│  ├─ ├─ Wiki Editor Toolbar
│  ├─ ├─ ├─ Wiki Editor Toolbar Support
│  ├─ User
│  ├─ Like
│  ├─ Notification

Explanations:

• The Getting Started is the same as in Option 1.
• Page: actions that are available when you're on a specific page, performed directly within the page display area, (view, edit, create, delete, etc.). Basically we labeled the "XWiki Standard Flavor" as "Page".
• We also plan to have the current page highlighted in the navigation tree, so users quickly see where they are in the documentation structure.
• Then the extensions are listed also in a logical order

Pros:

• Users don't lose context.

Cons:

• Deciding the navigation order of XS features may be difficult, what subject is more important than other depends on the user need.
• Higher cost.

Positioning Pages in the Nav Tree

Once it has been decided which extension or subject a page belongs to, for Option 1 and 3, we need a strategy to decide its position within the navigation tree. Choosing the order can be quite subjective, but the following criteria should be considered:

• List pages from most useful to less useful, considering how often a feature is used.
• Use the Common Criteria to help decide.
  • For example, both "Hide a Page" and "Change the Syntax" belong under "Page". "Hide a Page" is listed before "Change the Syntax" because hiding a page is used more frequently, while choosing a syntax usually happens only when creating a page.
  • Another example: the standalone WYSIWYG editor, also under "Page", has a very specific use case, so it should be listed lower in the tree.

Nav for Extensions

Option 1: A tree

The navigation tree in the change request application page (example):

├─ Subject #1 - CR creation
├─ ├─ Tutorials
├─ ├─ How-to
├─ ├─ ├─ Create a CR
├─ Subject #2 - Manage approvers
├─ Subject #3 - Review CR

• An automatically generated alphabetical list of all available extensions.

Option 2: A LD

Other Navigation Improvements and Cleanup

Also, introduce a left nav panel for the doc home page, for consistency and easiness of nav.

In order to achieve a clean navigation tree/breadcrumb, we need to:

• To hide:
  • Roadmap archives (no need for users to find that) or maybe better, move that page to the dev wiki
  • Technical active install pages
  • "Macros used on XWiki.org" page
  • Test Reports pages
  • Download, Try, etc
  • Admin tools app
  • "XWiki.org" space
  • Find how to hide the XWiki space

• To remove:
  • Remove https://www.xwiki.org/xwiki/bin/view/Main/Forge (too hard to explain and unnecessary nowadays)
  • Remove Test space

• To move:
  • Contribute -> to main wiki
  • Surveys pages -> under Feedback page
  • Drafts ->under Contributing (create Contributing space and hide it in the nav)

As an upcoming improvement, when Cristal is ready to move to xwiki.org web site, the "Documentation" top menu link will be replaced by a dropdown where both XS and Cristal are listed.

More generally the goal is to have the nav look like what's listed above.

Proposal 8: Landing Pages

• Add a "Landing page" type to the Doc XClass (see proposal 4). The rationale is that we could have used a "Reference" type for these pages but we don't want to display them when the reader is looking for reference pages as we don't think the reader will expect to find them listed. see rationale.
• Have a template for Landing Pages with the following structure:
  • A quick description of what the reader will find under that landing page
  • A short list of pages we want to highlight (e.g. see the "Navigation Tree"- option 2 proposal above), displayed in blocks (similar to Sponsored Extensions  on exo for the L&F)
  • A LD listing all doc pages that the landing page represents. Examples:
    • For the top level "Documentation" landing page, display all doc pages having a Doc XClass (for XS only, don't display non-budled-in-XS extensions by default at least)
    • For the "User Guide" landing page, display all doc pages having a Doc XClass with a target of "user" (for XS only, don't display non-budled-in-XS extensions by default at least)
    • For the "User Guide/Howto" landing page, display all doc pages having a Doc XClass with a target of "user" and a type of "howto" (for XS only, don't display non-budled-in-XS extensions by default at least)
    • For each Extension landing page, display all doc pages having a Doc XClass and that are children of that Extension page

Highlights Sections

We need clear criteria for defining which documentation pages should be included in the highlighted section of landing pages.

Common Criteria

• Relevant pages to newcomers
• Use Pages that are frequently accessed as a reference
• Pages that address common issues
• Pages that cover essential topics (useful for many situations, containing a lot of important information)

Note that the "Highlights" section is optional and should be used only when it helps users navigate a larger set of documentation. If a topic has fewer than 15 pages, this section is not needed, as all pages are already directly visible in LD.

Specific Criteria for each Type of Landing Page

* For the extension landing page (e.g.: Like):
 Include highlighted pages for the target, if there are pages that cover essential topics for that specific target.

• For the sub-extension landing page (e.g.: Like Application, currently, on the converted documentation pages, there is no sub-extension with more than 15 pages, but this will apply when we do):
  • The main howto/s of the essential topics of the sub-extension   This has been retracted, as now the documentation hierarchy has been refactored, removing the type and target landing pages for each extension. 
• For target specific landing pages (e.g.: User Documentation for XWiki Standard Flavor):
  • Focused on the specific target audience
• For type specific landing pages per target (e.g.: Howto Guides for Users ):
  • Include the main content of the essential topics for that type (e.g.: the main howtos, explanations, references, etc.).

Format

• The section can follow a layout similar to the Sponsored extensions block.
• Each card would contain:
  • The title of the documentation page as a clickable link.
  • A short description of what can be found in that documentation page.
• A maximum number of cards should be defined to be displayed (we initially considered 5 cards).
• See the example in draft for illustration.

Rules for Changing the Highlighted Pages

• Whenever a new page is added to the documentation:
  • Check if the new page is more “important” than the existing Highlights pages (using the Common Criteria).
  • This check should be done for all parent landing pages of the new page.
• When replacing a Highlights card:
  • Anyone can change it after asking for feedback on the xwiki matrix chat.
  • Only the documentation team has the rights to update the Highlights, therefore the doc team should be asked for updates.

Proposal 9: Nav vs Menu

Don't put any content from the the horizontal Menu of xwiki.org into the Navigation tree Panel, and don't add Documentation XClass to these docs (they're not targeted to a specific target user).

The rationale is:

• Keep the Navigation Panel for the Documentation of XS
• There's no need to have the Menu entries in the Nav tree since the Menu is visible on all pages already.

Also:

• Add the following docs to the horizontal menu (in About section). The main reason is that they're not targeted to a specific user category and they're not really XS documentation:
  • Compare with Confluence/MediaWiki
  • Active installs

• Move the links of documentation for Snippets, Extensions, Commons, Rendering in the dev guide somewhere
  • Snippets: This is unreviewed documentation, with security issues, so it might not go with the rest
• Rework the "Projects" page to make it simpler to understand and to accomodate the arrival of Cristal in it, see Move Cristal from Contrib to XWiki.
• Move FAQ into documentation (as howtos, explanations pages, etc) and out of the horizontal menu.

Proposal 10: Glossary

Rationale:

• Provide a common place for readers to read about XWiki terminology.
• Make it easy to link XWiki terms in wiki pages to a single place defining them.

Implementation:

• Use the Glossary Application
• When this issue is fixed, configure the Glossary Application to update pages on save, to avoid performance issues.
• In the meantime, configure the application to not make any change, and let the doc writers use it manually by using the {{glossaryReference/}} macro.
  • And only link the first occurence a glossary term per page.
• Create glossary pages as Diataxis Explanation pages, located in the place where that explanation makes sense in the doc hierarchy (i.e. NOT under the glossary app space).
• Use capitals for glossary terms.

Some glossary terms collected so far and that will need to be transformed into doc pages: Glossary Terms.

Proposal 11: Heading structure for Doc Pages

We propose having a fixed structure for each documentation page. This is achievable by having stable headings configured by default.

• 1st heading depends on the type:
  • Howto: Howto (or How-to or Steps)
  • Tutorial: Tutorial
  • Explanation: Explanation
  • Reference: Reference
• 2nd heading (optional): FAQ
  • Include troubleshooting questions, small and specific explanations, etc
  • Only for topics specific to the page and that should be not widely visible and findable from filtering from the top level of the doc
• 3rd heading (optional): Related
  • This heading includes links to pages that are on the same subject. This way we avoid info boxes that redirect to other documentation pages. These links are added manually.
• 4th heading (automatic): More
  • This heading includes a LT listing all children pages (see third bullet point of Proposal 6).

In addition:

• When the main content requires additional headings, put them under the 1st heading.
• Add a TOC

Implementation:

• Modify the Documentation Class to add 2 new properties:
  • A faq textarea property
  • A related textarea property
• Create a DocumentationClassSheet which will be bound to the DocumentationClass class
• See the POC:
  • Source: https://www.xwiki.org/xwiki/bin/view/XWikiOrg/DocumentationClassSheet?viewer=code
  • View & Edit examples: https://www.xwiki.org/xwiki/bin/view/XS/XWikiStandardFlavor/User/ViewPage/ChangeSyntax/
• Pros:
  • Consistency for all pages
  • Hints about how to fill the FAQ and Related sections
• Cons:
  • No RT ATM on the content editing part
  • A bit more CPU intensive and slower than a plain doc page since there's some velocity executed.

Proposal 12: Additional image styling rules

Gallery Macro

Whenever there's a need to display more than one image next to each other (e.g.: to show variations), it is considered best practice to use the Gallery Macro. This avoids cluttering the page with standalone images and not knowing to which image(s) the text above or below the images refers to.

Image Placement

When an image is followed by a detailed description of its content, it’s best to present the image first. This allows the reader to understand the context of the explanation, as describing an unseen image can lead to confusion.

Adding clear visual guidance in screenshots

Add clear visual guidance in screenshots about the topic being presented in the text, by:

• Surrounding the concerned element(s) with a square
• Using a Red square ("255, 0, 0" RGB value)

For example a screenshot showing the full XWiki UI in a section about how to edit a page would highlight the "Edit" button with a red square around it.

Pros:

• Easier for the user to follow
• Improves accessibility

Cons:

• Harder to maintain (when the UI changes, taking a new screenshot is not enough, we also need to add back the red squares)

Image Names

Currently, in the Documentation Guide the rule is to use CamelCase for image names, but from a SEO pov it's better to use Kebab Case, in a similar way as it's done in Page Names.

• Pros:
  • Image names also appear in URL when they are accessed, so it's good for consistency.
  • Improved SEO.
• Cons:
  • There are already a lot of rules to follow for images in documentation.

Migration Strategy for Attachments Names

When a new attachment (image, document, etc.) is added, its name should either be validated or automatically transformed into kebab-case (e.g.: My Image.PNG -> my-image.png).

There's needed also a migration strategy for attachments/images to adopt the newly proposed kebab-case format in xwiki.org. The strategy can follow a similar approach to the page migration and should be applied to:

• All attachments of pages located in the new location on the main wiki.
• Any new attachments of pages created on xwiki.org after the proposal is accepted.

Proposal 13: Standardizing page names/titles

Page Titles

Standardizing the titles of documentation pages helps ensure clarity and consistency for user navigation.

• For HowTos: Start with a verb, e.g. "Edit a Page", "Build an Application" (and not "Editing a page" or "Building an Application").
• For Tutorials: Same rule as for Howtos but more specific (since a tutorial is a HowTo applied to an example), i.e. the title is more specific, e.g. "Build a FAQ Application".
• For Explanations: Don't start with a verb, use a title that is the topic of the explanation (i.e. that answers "why"), e.g. "Simple and Advanced User Profiles" or "Conflict Resolution".
• For Reference pages: Same as for Explanations. Since the goal of a Reference page is to be extensive about a topic, the title must reflect that. E.g. "Image Macro Parameters", "Home Page UI" (full presentation of all the elements of a home page) or "Standard URLs" (full list of all standard URLs).

Page Names

Currently, XWiki doesn't seem to have any defined rules regarding the URL structure.

• On xwiki.org CamelCase is generally used:
  • https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/PageEditing/
  • https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/DistributionWizard
• On Extensions spaces are generally used:
  • https://extensions.xwiki.org/xwiki/bin/view/Extension/Action%20API
  • https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension+Manager+Application

Rules:

• Use Kebab Case. (See reasoning).
  • Convert to lowercase.
  • Don't include stop words (`a`, `the`, `on`, `when` etc.). (Full list of stop words).
• Page names should follow page titles as much as possible, but still follow the other rules
• Avoid repetitive page names in the URL path. This happens when a child page repeats the same word or a variation of it that is already present in the parent page name.
  • • For example, instead of ../wiki-editor-toolbar/wiki-editor-toolbar-support , the proposed alternative is: ../wiki-editor-toolbar/support . Even if “support” is too generic on its own, having the parent “wiki-editor-toolbar” provides enough context for search engines to understand the full meaning.
    • Example: If the page title is "Choose a Syntax when Editing", the page name should be "choose-syntax-editing", but considering the fact that the parent is ../edit-page/, the page name should be ../edit-page/choose-syntax.
    • Note: This rule is feasible because the LD filters are based on the page title, not the page name, so avoiding repetition in the URL will not cause duplications in LD results.

Migration Strategy for Page Names

We need to implement a name strategy for kebab-case and apply it to xwiki.org. This means that when a page is created, for example in this manner: [[Developer Guide]], its URL will automatically be transformed into ../developer-guide . We need to ensure that this applies also to extensions pages created on exo when new extensions are imported or added manually.

Initially, this strategy should be applied to:

• All pages located in the new "/Doc" location on the main wiki
• Pages linked from the horizontal menu 
• Pages linked from the footer
• When an existing exo page has been completely refactored into pages in the "/Doc" space and the only thing that remains is a link to the extension doc, also rename the extension at that point
• Any new page created on xwiki.org after the proposal is accepted

Proposal 14: Syntax for UI Elements

Option 1:

Whenever referring to a UI element in the documentation (such as buttons, menu items, tabs), use bold styling to distinguish it from the rest of the text.
For example: Select the content Syntax you want to use from the Page Syntax section inside the Page Information Panel.

Pros: Widely recommended in documentation style guides
Cons: Draws the eye strongly, even when it's not necessarily something important

Option 2:

Whenever referring to a UI element in the documentation (such as buttons, menu items, tabs), use "quotes" to distinguish it from the rest of the text.

For example: Select the content Syntax you want to use from the "Page Syntax" section inside the "Page Information" Panel.

Pros: Provides a cleaner, lighter visual distinction
Cons: Not the most common approach

Our preference goes to option 2 since we find using bold too distracting.

Proposal 15: Use Uppercase for XWiki Terminology

For terminology words (such as Syntax, Panel, Page) the best practice is to write them in plain text and uppercase. 

In order to decide if a word is "terminology" it should have a special meaning in XWiki, other than in the English dictionary (example: "Panel" when referring to the left or right Panel in XWiki). 

Also, XWiki concepts should be collected in a Glossary.

Proposal 16: The UI for the XProperties

This proposal is about the way the xproperties of the Documentation XClass from the Proposal 4 are displayed in the user interface, so the visibility of the metadata is improved.

As a result of Proposal 5: Location of documentation, in addition to the xproperties defined in Proposal 4, a new xproperty to indicate whether a page is intended for XS or for extensions not bundled in XS is needed. Like the other xproperties, this property will also be displayed in the user interface.

Option 1

• The Last Reviewed Date and Last Reviewer will be displayed on the same line as the "Last modified by [Name] on [Date] " - Last Reviewed by [Name] on [Date].
• The type (Tutorial, Howto, Reference, Explanation) and the target (User, Admin, Dev) will be displayed as pills, aligned on same line where the tags are currently shown.

Option 2

• Display all the metadata (type and target) in the top of the page, possibily on the same line with "Last modified by [Name] on [Date] " - Last Reviewed by [Name] on [Date].

Note: In the implementation, the Content Footer and After content header documentation pages could be used, they describe how the UI extension points are used to render content on the same line as the tags and immediately after the page header.

Proposal 17: Reference pages and tables

As a reminder, a Reference has the goal of presenting everything about a topic. The goal is to be extensive about a topic.

Reference pages must contain tables as a best practice because they present concise information and avoid verbosity. This way, there is also a visual separation from the other types of pages.

Proposal 18: Captions for Attachments, Tables

After brainstorming the idea of having captions for images and tables, here is the proposal on this topic:

To improve accessibility and align with WCAG guidelines, it is important that on documentation pages, images and tables have appropriate descriptions.

Note: This applies to all non-text content/attachments, but so far, on documentation pages, tables and images are the most common.

• Images:
  • The `alt` parameter should be used when inserting an image with the Image Macro, providing a meaningful description.
  • The `caption` parameter could also be used for adding brief visible content under the image, eventually specifying the version of the software the screenshot was taken in.
• Tables and Figures: They should be wrapped using the `figure` macro along with the `figureCaption` macro as in  Figure Macro, also providing a meaningful caption.

Note: As a conclusion of the brainstorming, this rule is not enforced as a must, but as a should, meaning it's highly recommended. This approach is chosen to avoid making contributions more difficult, as there are already many rules in place.

Brainstorm: Standard Table Style

To ensure consistency, all tables should follow the same styling.

Option 1: Using the `figure` and `figureCaption` macros

Use the `figure` and `figureCaption` macros as in Figure Macro. If we want to use it, we need to install it in xwiki.org.

• Pros:
  • Might be better for accessability and SEO because it express clearly that is a figure/table with a caption.
  • If we want to change the macro or stylesheet, the updates will apply everywhere.
• Cons:
  • Less flexible, we can’t have different table formats across pages (Although, since we want consistency, having the same format everywhere is actually desirable, so this is not really a con).
  • Some contributors may not read the doc guide and use directly the WYSIWYG editor for inserting a table instead of the `figure` macro.

Option 2: Using inline styling

- Use the bordered table style from the WYSIWYG editor toolbar or add with the Wiki editor the %class="table-bordered"% attribute to the table.
- Use style="margin-left:auto; margin-right:auto;" to center the table.
- Table headings in bold
- Include a `summary` that contains a short description of the table content to improve accessibility and clarity.

• Pros:
  • More flexible, editors can apply different table formats across pages. (However, since we want consistency, this is not really a pro in our case, but more of a con).
• Cons:
  • Doc contributors may use different styles if they don't take into account the doc guide.
  • Changes require manual edits everywhere.
  • Doesn't have semantic meaning as `figure` and `figureCaption` do

Brainstorming on forum about this.

• TODO: think about images too

Proposal 19: Perspective of the Documentation

Option 1

Document the text and UI for the LTS version and then add some ~{~{version since="..."}} macro to show how it looks for the latest version.

• Pros:
  • Users might not be yet on the latest version, so starting from the LTS shows the version that many people still use.
• Cons:
  • When the changes from the latest version will reflect also in the LTS version, changes are required to use the version macro with the before parameter. For example, the LTS is 16.10.11 and the sentence: "Some inconsistencies of wording were solved ~{~{version since="17.8.0, 17.4.5, 16.10.12"}} and the UI displays "Language." is added to a documentation page. When 16.10.12 becomes the LTS, the sentence needs to become "The UI displays "Language", but ~{~{version before="16.10.12"}} it displayed "Locale".

Option 2

Document the text and UI for the latest version and then add some ~{~{version before="..."}} macro to show how it looks for the LTS.

• Pros:
  • It needs less work because you don’t have to make other changes when the changes from the latest version are brought to the LTS version.
  • It pushes users to the latest version.

We prefer option 2

Proposal 20: Introduce a ~{~{deprecated}} Macro for Marking Deprecated Content Inside Active Pages

There are cases when the documentation contains deprecated content embedded in pages that are not themselves deprecated.

For example, a feature might be partially deprecated, or only a specific parameter, UI element, or behavior is outdated, while the rest of the page remains relevant. The ~{~{version}} can’t be used macro for this, because it already has specific rules and is not meant for marking deprecated text.

A ~{~{deprecated}} macro could solve the problem. The behavior could be:

• Wraps a block of text.
• Automatically adds styling (highlighted tag) indicating that the content is deprecated.
• Could support an optional parameter such as: since= (e.g.   ~{~{deprecated since="10.2"}}...~{~{/deprecated}} ).

Proposal 21: Add a “Documentation Resources” Section to the Documentation Guide

To improve the visual quality and realism of documentation, this proposal introduces a new section in the documentation guide dedicated to contributors who want to add screenshots or example content. The section suggests a predefined environment, provided as a XAR package to ensure that the examples are realistic, visually appealing, and close to real use cases. The use-case proposed is an Intranet environment.

For example, the environment should include predefined:

• Wikis:
  • Main Wiki: Home
  • Additional Wiki: Projects
• Users with realistic names: John Smith, Ana Smith, Alex Johnson
• Avatars:
  • John Smith, Ana Smith, Alex Johnson

    
    
    

• Emails
  • [email protected], [email protected], [email protected]
• Spaces:
  • Home Wiki:

    ├─ Welcome
    ├─ ├─ Introduction
    ├─ ├─ About Company 
    ├─ News
    ├─ ├─ Announcements
    ├─ ├─ ├─ Updates
    ├─ ├─ Events
    ├─ ├─ ├─ Hackathon

  • Projects Wiki:

    ├─ Project List
    ├─ ├─ Project 1
    ├─ ├─ ├─ Overview
    ├─ ├─ ├─ Strategy
    ├─ ├─ Project 2
    ├─ ├─ ├─ Overview
    ├─ Meeting Notes
    ├─ ├─ Strategy 1
    ├─ ├─ Strategy 2
    ├─ Best Practices

• Text and Attachments: The content on all pages is similar to real content but generated, attachments are organized realistically to make the pages appear like true content. This way, a realistic structure and layout are presented, while keeping the actual text content generic.

The idea is to encourage contributors to provide screenshots and examples using realistic examples, making the documentation more engaging.

Proposal 22: When to Use Landing Pages

Context: We have experimented landing pages on xwiki.org, and several remarks have been drawn to improve the doc structure.

1. Use explanation pages instead of topic landing pages.

   Current topic landing pages contain summaries, highlights, and a section with search and LD. In practice:

   • summaries are hard to maintain as they describe what's below, but the number of children pages is constantly growing
   • summaries tend to become explanation content and can duplicate information from actual explanation pages under the same topic
   • landing pages are not findable in Live Data because they don't have attached an Object of type DocumentationClass

   Therefore, the proposal is to use explanation pages instead of topic landing pages.

2. Move Highlights and Search into the Documentation Sheet and XClass

   This means include the "Highlights" section and the search box on every documentation page. Both will be displayed under "Find more about the current topic" (which replaces "What are you looking for?"). The "Highlights" section is still optional, as proposed and agreed before.

3. Keep Landing Pages Only for Non-Product Documentation Pages
   • Pages that represent documentation targets and types (e.g., Users, Admins, How-tos, Explanations,..) should continue using landing pages in their current form.
   • The existing summary + highlights + search + LD structure remains the same.

Note: The landing page template can be removed from the “Create Page” options, since only the documentation team needs to create and maintain landing pages, and they can do so directly using the LandingPage object.

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 Macro Reference Page

1. Description: A short and clear explanation of what the macro does, its purpose, and typical use cases.
2. 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
3. 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

To avoid conflicts with existing page title rules (e.g., all how-to's and tutorials must start with a verb ), 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: For rendering macros and UIXPs there might be the most cases when wanting to use a page name that's already taken by another page. Therefore, a generic rule to treat the cases when a contributor wants to name a page with a name that is already used, in the same location, causing a conflict. 

Additional Guidance for Proposal 13: Page Names

When you want to name a page, but another page with the same name exists in that location:

• you need to provide more details in the name of one of the page
  • the details should not be related to the target/type of the page, since this information is already present in the URL) 
  • the details shouldn't break existing page names rules.

Proposal for search

Implemented Search box without a separate proposal, see https://forum.xwiki.org/t/feedback-on-the-new-documentation/17943/9?u=elenicojocariu.

Proposal 24: Change the splitting of documentation from Product > Target > Topic to Product > Topic > Target

Context

Currently, documentation is splitted by Product (XS and Extensions), then by Target (User, Administrator, Developer). The navigation changes based on what Product and Target the user selects. So, after selecting the Product and Target a list of topics is listed below in the "XWiki Standard" Navigation/ "Extensions" Navigation. This helps users filter the page they might be looking for based on their role in the wiki. Topic pages (top level pages) are pinned in the navigation by relevance. 

In the current documentation of XWiki, documentation is splitted by target before topic. It was not considered before to not have targets before topics. In the forum proposal for navigation tree Proposal 7, the two options proposed were: 

• Option 1: Target > Topic > Type,
• Option 2: Target > Type > Topic.

The majority voted for option 2 of the Navigation Tree proposal.

The target and product concepts were then moved outside of the navigation, (as we currently have), and a third option was proposed: 

• Option 3: Nav ordered by Topic only (with 4 extra entries for the types), (see Vincent's comment.) 

Option 3: having documentation split by topic only in the navigation was finally agreed: Forum comment, while also having another navigation panel for the targets. To get all documentation for an extension, you need to go on exo and click on the "Documentation" button (Forum solution).

Advantages of having it this way

The advantages discussed on the forum highlight why is better to have documentation splitted by topics only, considering the fact that targets are already selected in another panel, before topics. However, some advantages of having Target > Topic:

• Not having an extra level in the navigation under the topic
  • E.g., avoiding this:

    
    ├─ Page
    │  ├─ User
    │  ├─ ├─ Edit a Page
    │  ├─ ├─ Simple and Advanced Editing
    │  ├─ ├─ ...
    │  ├─ Administrator
    │  ├─ ├─ Administer a Page
    

• Readers look for different things, a regular user who just uses the feature in XWiki would not be interested in APIs, etc. Some topics are only relevant to specific targets and don't have documentation for all roles. 
• We use the "Related" section to point to other target's documentation pages, and we do not have in the navigation a page for user, near a page for developer, etc.
• Improved on-boarding experience.
• Not mixing targets within the same page hierarchy.
• This split, combined with the order (User > Administrator > Developer), also conveys the idea of levels of responsibility, where the administrator role includes user capabilities, and the developer is the highest level.

Disadvantages

• Harder to get a complete view of the topic. 
• Unable to export a PDF for example for a topic with the full documentation.
• Readers may not always identify with a single target.

Proposal: Have documentation split by topic and only then by target

In "/documentation/xs", instead of having cards for each target there will be cards for each existing topic, no matter the target (e.g.: "Base", "User", Notifications", "Installation", "Applications", "Like", "Data Model",...etc). When clicking on a topic, there is the possibility to split again documentation by target. Below, option 1 is for adding an extra level in the page hierarchy and navigation for each target, while option 2 is for not adding an extra level for the splitting.

Option 1

Adding a level for the target in the navigation, but not in the page hierarchy, by making the Target level not clickable.

Product
  |_ --- User Topics --- (not clickable)
  |_ topic 1
    |_ subtopic 1
  |_ topic N
  |_ --- Administrator Topics ---
  |_ topic 1
  |_ topic N
  |_ --- Developer Topics ---
  |_ topic 1
  |_ topic N

Advantages:

• Easy to implement.

Disadvantages:

• Creates confusion as some tree nodes are clickable, some are not.
• Breadcrumb different from page hierarchy.

Option 2

Adding a level for the target in the navigation (and page hierarchy).

Advantages:

• Easy to implement, just create new pages for each target for each topic/subtopic.
• Documentation pages have a proper parent, making it not to mix documentation pages for different targets in the navigation.

Disadvantages:

• Raises the question: "Where in the hierarchy do we introduce the target level?" (e.g., under the topic, or under subtopics?), leading to potential duplicates in the navigation.
  • Example:

├─ Base
├─ ├─ Page
│  ├─ ├─ User
│  ├─ ├─ ├─ View a Page
│  ├─ ├─ ├─ Create a Page
│  ├─ ├─ ├─ ..
│  ├─ ├─ Administrator
│  ├─ ├─ ├─ Administer a Page
│  ├─ ├─ Developer
│  ├─ Wiki
│  ├─ ├─ User
│  ├─ ├─ ├─ ..
│  ├─ ├─ Administrator
│  ├─ ├─ ├─ ..

or 

├─ Base
├─ ├─ User
├─ ├─ ├─ Page
│  ├─ ├─ ├─ View a Page
│  ├─ ├─ ├─ Create a Page
│  ├─ ├─ ├─ ..
├─ ├─ Administer
├─ ├─ ├─ Page
│  ├─ ├─ ├─ Administer a Page
│  ├─ ├─ ├─ ...

• Does not solve the issue of exporting documentation in a single PDF for a topic/subtopic, since content is fragmented across targets.
• Too many levels => too nested. 
• Can duplicate subtopics (e.g. "Page") under each target.
• Not all topics/subtopics have documentation pages for all the targets.  
• Targets would be under each topic/subtopic the levels => redundant. 
• If we stick with this, there is no path to improve (as in option 2).

Option 3

Not adding a level for the target in the navigation and convey the separation using other methods: having in the page title the target, use some styling (icons). The major advantage of selecting this option is that it allows to build additional improvements on top of it. After mixing all the doc pages for all targets under the same topic, we would probably re-group the pages below.

Idea 1: Mixing the pages in the navigation

Having the pages just below the topic, without any other level. The breadcrumb will list all topic pages for all targets at the same level.

Advantage:

• Can be combined with Idea 2 in the future to have a visual separation of doc pages. 
• Can be combined with pinning the pages per targets (display user doc first, then admin, ..).
• Can be combined with Idea 3 in the future to filter the target.

For example:

├─ Page
│  ├─ Edit a Page
│  ├─ Simple and Advanced Editing
│  ├─ Administer a Page
├─ Like
│  ├─ Like (or Unlike) a Page
│  ├─ Administer Like Preferences
│  ├─ Like API

Issues:

• Sorting the pages to display first pages for Users, then for Administrators, then for Developers is needed (custom code?). This can be achieved by pinning the pages, but then every page will need to be pinned => Hard to maintain.
• Many irrelevant pages for the user displayed in the page hierarchy, making it harder to find what they are looking for.

Idea 2: Use icons per targets

For example:

•   for user doc pages
•  for administrator doc page
• / / /   for developer doc pages

Advantages:

•  Nice visual separation for each target.

Issues:

• Custom code is needed to display in the navigation the icons.
• Sorting the pages to display pages in order (User > Admin > Devs) / or having to pin them.

Idea 3: Filter in a separate section of the panel the target

Add a dedicated section in the panel with three target options (User, Admin, Developer) each with a checkbox. Readers can select one or more targets, and the content tree below dynamically updates based on the selected audience. This allows to have all docs under the same topic, without adding a separate level.  If no target is selected, all docs are displayed in the navigation.

Advantages:

• Probably the best solution for the readers as it's flexible.
• Keeps all related documentation under a single topic
• Can be combined with idea 0 and idea 1.

Issues:

• Complex to implement and a lot of issues to solve.
• Different breadcrumb if at least one target is selected. (The breadcrumb will list all topic pages for all targets at the same level).
• Custom code is needed for implementing the filtering (extending or reworking the doc tree/macro)
• Clarifications for the filtering behaviour is needed:
  • What if a selected target has no pages in a topic? Should empty topics be shown or hidden?
    • For example:  What happens if the reader selects "Developer", but the topic has no developer pages. -> Do we keep the topic and display nothing under it? Do we filter out also the topics that have no subpages for that target?
  • If a child page matches the filter but the parent does not, should the parent be displayed?
    • For example: The user selects "Administrator" as the target. The navigation lists "Administer a Page" targeted for admins, but the parent page "Page" is dedicated for Users. Is "Page" also displayed in the navigation?
  • When navigating to a page outside the selected target, should the navigation filter reset, update, remain the same?
    • For example: If a reader selects "User" (filtering the navigation to User docs) and then clicks a link to a page targeted for Administrators, how should the navigation behave? Should the filter reset, adapt to the new page, remain the same as selected previously ?
• Currently, each topic page (e.g. "Base" has a type and a target (check proposal: When to use landing pages ). Landing pages for topic pages were originally removed to allow topic pages to have the DocClass object and appear as proper documentation entries in the LiveData. The topics and subtopics pages targeted for users are different from the ones targeted for administrator, (e.g. "Page"  for Users is different from the "Page"). This raises a key question: should we revert to using landing pages again for topic pages, or support multi-target topic pages (i.e., allow a single page to be associated with multiple targets)?

Idea 4: Having a visual separation in the navigation based on some color codes.

This idea was proposed by a participant during the developer meeting.
For example:

•  blue  user doc pages
•  orange  for admin doc pages
•  purple  for developer doc pages
  ├─ Page
  │  ├─  Edit a Page 
  │  ├─  Simple and Advanced Editing 
  │  ├─  Administer a Page 
  ├─ Like
  │  ├─  Like (or Unlike) a Page 
  │  ├─  Administer Like Preferences 
  │  ├─  Like API 

Issues:

• Doesn't look good or professional at all.
• Custom code needed.
• Sorting the pages to display pages in order (User > Admin > Devs).
• Deciding what colors are suitable for each target and why.
• Not the best approach.

Note: the options above will apply to both documentation for "XS" and "Extensions".

Option 4

We could consider that the documentation for users and administrators is closely related, that many of the concepts overlap, the main differences being the permissions which unlock different features/ UI elements, thus it can make sense not to split topics strictly by target audience between users and administrators. The developer documentation, however, could remain separate. This is the approach used in the documentation of Atlassian: user and administration topics are grouped together, while developer documentation is placed in a separate section called “Other documentation”. Atlassian Documentation.

Advantages:

• each documentation page has the target badge on it, allowing readers to immediately see who the content is intended for when they open the page.

Disadvantages:

• Doesn't solve the initial problem. 
• Creates confusion and inconsistency between targets.

Proposals not yet sent on the forum

Proposal 25: Use Review Class for Documentation Quality and Validity

The ReviewClass was proposed in Proposal 3 and is already implemented in the Documentation Application. It was initially meant to mark reviewed content from the perspective of the Documentation Guidelines.

Now, it is proposed to extend its usage to also validate the actual content: whether the information is accurate, complete and correctly understood and conveyed in the content.

Proposed workflow

After refactoring content into new location, the contributor should request a review. This can be done by sending a message in the #xwiki chat, either addressed to a specific person (e.g., the original author of the documentation page/the developer of the feature), or not. The contributor specifies the type of review needed:

• Validity review: content is accurate, complete, correctly conveyed and understood.
• Quality review: content, location, navigation comply to the Documentation Guide.

The reviewer will add an object of type ReviewClass and fill-in with a date and its name as a "Last reviewer", and then provide the feedback. (A contributor can't put their own name as a reviewer.) For providing the feedback there are the following options:

• Option 1: Use the #xwiki chat.
• Option 2: Use the Annotations (if enabled).
  • Currently, comments (and implicitly annotations) are disabled on xwiki.org (Forum proposal. Annotations are fast, could help at tracking whether the feedback was correctly addressed. 

Question: Should annotations be re-enabled, or is the chat preferred? Personally, I'm in favor for enabling annotations on the Main wiki. 

Reviewed pages are tracked in: Documentation Reviews.

The advantages of having a structured way of reviewing documentation:

• Prevents losing or misinterpreting information.
• Provides checks for documentation validity beyond just following the documentation guide. 
• Ensures content is accurate.

Additional Proposal: Work in Progress Visibility

Add a step in the Migrate and Refactor Documentation to include a "WIP" banner on pages being refactored. The "WIP" banners will also include links between the current and refactored documentation, allowing users to easily navigate between the pages under refactoring and their updated versions.

Proposal 26: Moving the Documentation Guide from the Dev Wiki to the Main Wiki

Context: The current Documentation Guide is on the Dev Wiki.

Why?

• You don’t need to be a developer to contribute to the documentation. The Documentation Guide is intended for anyone who wants to contribute to the documentation. Keeping it on the Dev Wiki implies it's dev material, which is not true.
• Easier to access: Documentation lives under "/documentation" on the main Wiki. Having the guide elsewhere makes it harder to find, especially for new contributors. 
• All documentation-related resources in one place: consistency with the ongoing migration process. The Extension Wiki’s content is already being migrated to the main Wiki. Moving the Documentation Guide there aligns with our goal of having the documentation in one place.

What to do

• We could use  "../Main/documentation-guide/" as a location.
• On the horizontal menu, On the "Contribute" button in the dropdown, "Documentation Guide" will be listed.
• We'll keep the links though from the dev Wiki pointing to the doc guide.
• When moving the Documentation Guide pages, make sure to use kebab-case for the new page names.

Brainstorming: Gallery Macro vs. Image Macro

I’m trying to understand why the Gallery macro displays images in better quality than the Image macro. With the Image macro, I need to take the screenshots with the browser window resized (using the Inspect Element) to match the width corresponding to the size parameter to avoid quality loss. But taking the screenshot in a width corresponding to the size parameter changes the page layout (most of the times) because of responsiveness. One problem is that this can confuse readers who compare the documentation with their own wiki (especially in another language) and expect the layout to match.

The Gallery macro doesn’t have this issue: it doesn’t require a size parameter, and it fills the background around the image, keeping the quality and layout stable. So I want to understand why there is such a difference in image quality between the two macros.

Examples:

• Image macro with size=extra (960px) applied to a screenshot that was not taken at 960px

   
  The image loses quality. The text is barely readable.

• Image macro without specifying the size parameter with the same image as above

  
  The image becomes very large and takes too much space, making the layout look unbalanced with the rest of the content.

• Gallery macro with the same screenshot:

  

  The image keeps good quality and is nicely contained inside the gallery frame, without affecting the page layout. The image itself, though, is a bit too small.

• Image macro with a screenshot taken at 960px

  
  The image quality is fine, but the page layout changes due to the resizing (no side panels).

Other

Todo: make sure that all points from https://forum.xwiki.org/t/documentation-improvements-ideas-related-to-doc-organization-for-xwiki-org/15714 are included in this design page.

Stuff to move into proposals:

• Consistency between nav panel and breadcrumb tree -> achieved already 
• Idea: Tags
• Idea: Doc tracks per understanding level (beginner, intermediate, expert)
• Idea: Having an "Advanced" macro to mark content for advanced users. 

Pages to rework about documentation

• Contrib (sections "Documentation", "Documenting") 
• Contributing
• Help

Brainstormings not yet sent to the forum

-

User Survey: Feedback on the New Documentation

1. How easy is it for you to understand, navigate, and search within the new documentation?
   Please describe any areas that feel clear or confusing.
2. How does the new documentation compare to the old one?
   What feels improved, and what (if anything) felt better in the old documentation?
3. How easy is it for you to find specific information or complete a task using the new documentation?
   If possible, describe a recent example where you tried to find something.
4. How do you feel about the new documentation structure?
   What is the best aspect that has been improved, and what else could be improved?
5. What is your impression of the new documentation rules and guidelines for doc writers and contributors?
   Do they make the documentation clearer and more consistent? Do you find them too restrictive/ difficult to apply?
6. Please try to locate a specific page or piece of information in the new documentation (choose any topic).
   How easy or difficult was it? What helped you, and what got in your way?
7. Do you have any suggestions for improving the new documentation or the contributor guidelines?
   Feel free to mention content, structure, navigation, or anything else.
8. How do you feel about the overall direction of the documentation project?
   Should we adjust anything in terms of structure, organization or goals?