XWiki.org Documentation Reorganization (batch 8)

[vmassol]

@elenicojocariu

Pages that are frequently accessed

This is not the right link. The link should be to GA or Matomo.

@elenicojocariu

For the extension landing page (e.g.: XWiki Standard Flavor):

• Take into account pages for each target

I don’t understand what you mean. What does “take into account” means? Does it mean there MUST be at least one card for each type? Does it mean that there must be equal number of cards for each target? Something else?

Also right now on https://www.xwiki.org/xwiki/bin/view/Doc/XS/Extensions/XWikiStandardFlavor/ , as a reader, I don’t see which card is for which target…

@elenicojocariu

The main howto/s of the essential topics of the sub-extension

Why howtos? Why not tutorials or important explanations or …?

@elenicojocariu

For target specific landing pages (e.g.: User Documentation for XWiki Standard Flavor):

• Focused on the specific target audience

That doesn’t mean much to me. You’re already on a landing page that is targeting a specific audience so you cannot be more specific and that cards should focus on something else, like simply using the common criteria listed above.

@elenicojocariu

• For type specific landing pages per target (e.g.: Howto Guides for Users):
  • The main howto/s of the essential topics

Same as above. Why howtos?

@elenicojocariu

A maximum number of cards should be defined to be displayed (we initially considered 5 cards).

It’s not clear what you’re proposing. Are you proposing 5 or are you asking everyone to reply with a figure that they would like to see?

@gabrielc

could the highlights be changed? If so, how often? (keep in mind it could mess with the muscle memory of docs users)

Good point, what’s the process for updating the highlights section?

IMO it should be the following (added to the doc guide):

• When someone adds a new page to the doc, check all the parent landing page of the new page and verify if the new page is not more “important” (using the common criteria) than highlights already listed and if so, update them.

@gabrielc

what’s the maximum number of entries in a highlights card?

1 entry per card and 5 cards max.

@gabrielc

specifically, what criteria would be used for picking the pages?

See common criteria above.

@gabrielc

A scoring based on multiple criteria would probably be one of the better options. At the same time, it would be overkill and too much of a hassle to take out your pocket calculator whenever you want to add some links to a page. There are some criteria you can’t even objectively calculate (e.g.: how would you differentiate between common issues and essential topics?).

In this case, I think it would be best to have a couple of entries reserved for different criteria.
E.g.:

• 2 pages relevant for newcomers (depending on the page, if it’s a complex topic, you could already assume the reader is advanced)
• 2 frequently accessed pages, to make navigation easier
• 1 page that addresses common issues & 1 for essential topics

This is just an example on what I perceive to be important tho. More opinions are necessary.

It’s interesting but I feel it’s too complex to follow. The highlights section is an editor’s pick and it’s opiniated. It’s an opinion and is thus subjective.

I think the rule could be one of the following:

1. When someone wants to replace a highlighted card by another one, it should be asked on the xwiki matrix chat (alternatively it could be asked on the forum but that’s too heavy IMO).
2. Or, only the doc team should be responsible for highlights and they should be the one updating them. When someone thinks a highlight should be change, we should ping the doc team on matrix and ask about it.

Thx!