XWiki.org Documentation Reorganization (batch 7)

Development
,
1

Hi everyone! :waving_hand:

In addition to the other proposals, we (@vmassol, @paulinebessoles and myself) propose to have standardization across documentation pages in various aspects.

Proposal 12: Additional Image Styling Rules

Besides Image styling for xwiki.org, we suggest other image standardizations to improve visual consistency:

Gallery Macro

Whenever there’s a need to display more than one image next to each other (e.g.: to show variations), use the Gallery Macro in order to avoid cluttering the page with standalone images. For examples, check:

Image Placement

When including an image to illustrate a specific context, provide a description of its content, and make sure to present the image first and then its description. This way, the readers can immediately see what is being described, as explaining an unseen image can lead to confusion. See how this is applied in:

Clear Visual Guidance in Screenshots

Screenshots should include a red square (“255, 0, 0” RGB value) surrounding the concerned element(s). For example, see how it’s done in:

Pros:

  • Easier for the user to follow, clear visual guidance
  • Improves visual consistency

Cons:

  • Requires more maintenance (UI changes require both a new screenshot and re-adding the red squares)

Proposal 13: Standardizing Page Names and Titles

Having standard rules for the titles of documentation pages helps ensure clarity for the reader. Each type of documentation pages (Howto, Explanation, Reference, Tutorial) should follow a pattern for both the page titles and names.

Page Titles

  • For Howtos: Start with a verb.
  • For Tutorials: Same rule as for Howtos, but the title should also include the specific goal.
    • “Build a FAQ Application”
  • For Explanations: Avoid starting with a verb. The title should reflect the topic being explained.
  • For References: Use the same approach as for Explanations, but ensure the title reflects that the content is extensive about the topic.

Edit: Proposal about Page Names has been updated, please check Improve Page Name & URL Structure

Page Names

Page names (used in the URL) should be short and meaningful. They should:

  • Follow page titles
  • Don’t include spaces or dashes
  • Don’t include articles (a, the, on, etc)
  • Use CamelCase

For example, if the page title is “Change the Syntax when Editing” → page name: ChangeSyntaxEditing.

Page Names for Extensions

Context : the extension import feature on Extensions creates the page name based directly on the extension name, which does not follow the page naming strategy mentioned above.

We propose updating the import feature so that it generates URLs (page names) consistent with the established naming rules.

Also, when bringing extension documentation on the main wiki (see Proposal 5 batch 2), the extension documentation page names should also be renamed according to the page name strategy.

Proposal 14: Syntax for UI Elements

When referring to UI elements in the documentation (such as buttons, menu items, or tabs), we propose adopting a consistent styling approach.

Option 1: Bold styling

Example as it might appear in the documentation: 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: Quotation marks

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, as we find using bold too distracting. Option 2 is also what we’re currently applying in the converted documentation pages at the new location.

Proposal 15: Use Uppercase for XWiki Terminology

We propose to write each XWiki-specific term with a capital letter (uppercase), to clearly distinguish its generic meaning in English.

A word should be considered “terminology” if it has a specific meaning in XWiki, different from its standard dictionary definition.

For example:

  • “Panel” when referring to the left or right Panel in XWiki is considered terminology, while “panel” in a generic sense is not.
  • “Page” in XWiki represents a specific document structure (with metadata, content, history, etc.), which differs from the generic meaning of a web page.
  • See list of terminology we’ve collected so far.

In addition, XWiki concepts should be collected in a Glossary so that readers have a single place to refer to for understanding specific terms.
A proposal related to creating a shared space for readers to learn about XWiki has already been made (see Proposal 10 Glossary.)

Thanks!

2

I’m fine with the cost of this small additional step.

Did you consider using a dash (-) for the word separator instead of upper-cased letters?

1 Like
3

We did not. This is not something currently used on xwiki.org and we didn’t consider it. We could (and should) consider it. It would be a major change though.

I’ll talk to @elenicojocariu and @paulinebessoles about it.

Thx

3 Likes
4

Hi!

Please check the new thread with the updated proposal about page naming and URL structure on XWiki.

Thanks!

5

Hello!

As a follow-up of the proposal for Improving Page Name & URL Structure for xwiki.org, another subtopic under the Proposal 12: Additional Image Styling Rules concerns the naming convention for images in documentation.

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.

WDYT? Thanks!

1 Like
6

I’m +1 to have the same rule for all kinds of resources (i.e., kebab case everywhere, if we agree to go that way).

That’s better for consistency and SEO.
I’m not sure if we have support for attachment currently (e.g., auto apply of url rules when uploading attachments).

2 Likes
7

We don’t but we should indeed, see Loading...

8

+1

+1

+1

+1

+1 (and we should introduce as much tool support as we can)

+1

+1 for that option

+1

1 Like
9

Thanks, Manuel!

Please note that what we’re currently doing at the new location of documentation is option 2 (Quotation marks). Bold attracts focus, even when the information is not critical.

10

Mega plus here (including option #1).

1 Like
11

I’m in favor. For the sake of consistency, SEO, potentially even accessibility.

12

Regarding bold: TBH I’m really really close to -1 to use bold because there’s no reason to highlight it vs other words or sentence parts which could be even more important. It’s distracting and also it’s less clear than quotes that it indicates something from the UI (ie something you’re pasting as is) and not some word that is part of the sentence.

1 Like
13

+1 with the proposal, but I also want to add the necessity to clarify the version of XWiki displayed in the screenshot. As I already wrote in some other topic, it’s frequent that the screenshots remain a lot of time and even if the focus is put in some part of the UI, users might be surprise to see a difference in some menu, fonts, etc. So it’s easier to understand the image if they see that the screenshot was taken for a version of XWiki that is 2 years old for example.

Why not using a typewriter font format for those elements? Else I’m +0 with using quotes and -1 for bold.

I’m afraid that the mix of 14 and 15 might make some sentence very ugly to read…

Something like: In an XWiki Document each XObject is named using a Reference: you can edit them by clicking on the “Object Editor” button and searching in the “Search toolbar” for the Reference.

So for now I’m -0, the glossary makes sense, but using systematically uppercase might be a bit overkill.

14

+1

15

Not sure if you’re talking about attachments or not here. In general I’m ok with the proposal, but we’d probably need some attachment naming strategy then.

1 Like
16

One idea would be to put this rule as a “should”, similar to the brainstorming around using captions for images/tables.

We have the version macro, but we currently use it to document new features or to indicate changes in an existing feature, specifying the release during which those changes were introduced. Ideally, when indicating changes in an existing feature, the associated screenshots should also be updated.

Note that the fact we’re using a red square to highlight the concerned UI element helps the user to focus only on that element, not giving much attention to other UI elements in the background that might be changed in the future.

Thanks!

17

Yes, it’s about attachments. Indeed, similarly to the migration strategy for page names and URLs, we’ll need a migration strategy for attachments as well. Thanks!

18

As a follow-up of this proposal: Kebab-case for Image Names, there’s needed a naming strategy for attachments to use kebab-case, and also a migration strategy to adopt it on xwiki.org.

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).

The strategy can follow a similar approach to the page name 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.

WYT? Thanks!

19

@surli There is also the xproperty of the Documentation XClass: The last reviewed date which isn’t yet displayed in the UI but has been proposed to be shown: The UI of the XProperties. The last reviewed date property could be an indicator of how fresh the screenshots are in a documentation page, even if the version number is not specifically mentioned.

20

+1 for proposal 14 option 2, given we also agree that bold will not have any meaning beyond “important”.

With option 2., we say “all UI element names must be done in quotes”, but does this also imply “all quotes are UI element names”? If yes, I think we should settle on a specific set of quotation marks specifically for XWiki references.

+1
I agree, I believe it’s already followed in a lot of already written documentation in practice. One thing I believe will be more difficult will be to make sure every concept we capitalize actually has a glossary entry and a proper explanation :slight_smile:

Sidenote: There’s a whole rabbit hole about what exactly is meant by capitalization. For reference, from what I could see on the Glossary, this means for us that every single component word is capitalized.

Thanks!
Lucas