Clear criteria are needed to define which documentation pages should be included in the “Highlights” section of Landing Pages. We propose to have the following:
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.
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
I think the Highlights section is a good idea. But I think there should be some guidelines around what gets added there.
could the highlights be changed? If so, how often? (keep in mind it could mess with the muscle memory of docs users)
what’s the maximum number of entries in a highlights card?
specifically, what criteria would be used for picking the pages?
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.
This is not the right link. The link should be to GA or Matomo.
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?
Why howtos? Why not tutorials or important explanations or …?
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.
Same as above. Why howtos?
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?
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.
1 entry per card and 5 cards max.
See common criteria above.
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:
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).
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.
Above in the proposal it’s mentioned that we initially considered a maximum of 5 cards per Landing Page. And each card has one entry (i.e one doc page).
We have several types of landing pages, as described in
and for each type the general idea is to pick having in mind the Common Criteria and then with the focus being on what each type of landing pages contains (user doc/ explanations/ is an extension etc)
This sounds like a good idea overall, but I’m afraid it may not be applicable in every case. We shouldn’t enforce a specific number of each criterion since each topic has different needs.
Yes I know but al the committers can request access and for doc writers, we can also make it available to them. It’s still the right location to find what pages are the most accessed.
I should’ve been more clear indeed. When a reader lands on an extension’s landing page, we don’t know whether they’re a user, an admin, or a developer. That’s why the landing page shouldn’t only contain highlighted pages for users if there are also important admin or developer pages. What I had in mind when proposing this was to have at least one doc page highlighted for each target on the landing pages of each extension (if pages exist for more targets), but only if that page covers an essential topic for that specific target.
For example, alongside the highlights for end users, we could also have for admins a page on how to enable the extension, or for developers a page on how to configure something on that extension.
So far, when converting doc pages to Diataxis, I’ve found that howtos are usually the most suitable for highlights in this context. They’re less general than tutorials, and are often similar to a “getting started”, offering a simple first interaction with the feature. And they frequently redirect readers to other documentation pages about that feature.
Sorry, not only howtos, for each type-specific landing page per target (a how-to landing page, an explanation landing page, etc.), include the main content of the essential topics for that type.
By essential topics I mean those that cover the most important information, are useful in many situations, or serve as key entry points for understanding and using the feature.
Thanks for the feedback! I’m going to improve the proposal accordingly.
After the feedback above I propose an update of the proposal:
For getting the pages that are frequently accessed use Matomo.
Regarding “Specific Criteria for each Type of Landing Page”,
For the extension landing page
Include highlighted pages for each target, if there are pages that cover essential topics for that specific target. For example, if the highlights already include pages for users, but there are also important pages for admins, (e.g.: how to enable the extension) those should be highlighted as well.
For type specific landing pages per target
Include the main content of the essential topics for that type (e.g.: the main howtos, explanations, references, etc.).
In addition, it’s indeed a great idea to have a set of rules regarding modifying the Highlights cards:
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.
Thanks Vincent & Gabriel for suggesting the improvements and for the ideas!
We need rules so we know how to update the highlighted section when new pages are added. Some landing pages have only 1-2 highlighted pages now, but when new pages appear, we need to decide if they should go in the highlighted section or not.
This rule is one from the set of rules:
Other pages that are rarely visited but contain useful information can be already covered in the other rules from the set.
It might be good to highlight it so it’s immediately accessible, without searching.
Are those criteria ranked by importance or each of equal importance?
Overall I’m +1 for adding highlights on landing pages.
I don’t have a strong opinion on what pages should be highlighted, but I think it’s important to keep highlights consistent. E.g. I know the page I’m searching is the second highlight on this specific landing page, I can get there from memory, but if it’s moved it messes up my utilization. So at least monitoring changes made to highlights is a good idea IMO.
P.S. it could also be quite a security liability to keep these open. If the doc is nice and everyone uses our navigation instead of googling the name of the feature they look for, those highlight buttons will be on the path of a lot of users. Someone with intents clashing with the community wellness could edit just one or a couple links to bring users outside our doc or promote a product… Right now IMO it’s not such a problem since the most useful navigation links are only editable by admins.
Personally I’d have gone with 3 or 4, it fits nicely in a line of cards, but anything below 7 is alright with me.
With the old documentation, things like the menu bar or the welcome page were not editable by anyone without the rights. IMO these highlights could stand in the same category. They don’t have to change often to work well and they could compromise the whole documentation if messed with. Thinking about it, it’s exactly the kind of things where change requests would fit well. Anyone can make a change request to the highlights, and the doc team members, after checking there isn’t anything malicious, can validate the change.
So I understand the idea behind having highlights but I’m a bit mixed about all those rules as I’ve the feeling it will create friction for maintaining them on the long run.
I’m not sure I would include frequently accessed pages in the criteria: let’s say you have a page containing almost nothing but targeted by some bots and accessed many times, suddenly it enters in the criteria for being highlighted and it means nothing.
Also common criteria are simple enough but I think specific ones are really too complicated… I’m not sure we need all this if at the end we just need to ask on the chat for changing the highlight. It sounds like it would be better to only have a small set of easy to understand criteria to say yes or not for performing the change: in any case there will always be discussion.
So I’d say I’m +0 to have highlights, -1 to have frequently accessed pages as criteria, -0 to the specific criteria list.
This proposal is not about having highlights in general, this was already agreed on Proposal 8: Landing Pages. This proposal focuses on what pages specifically we allow on the Highlights section.
Thanks!
Since both Manuel and Simon addressed the issue of having the frequently accessed pages on Highlights:
I’m proposing to change from the Common Criteria the sentence "Pages that are frequently accessed" → to "Use frequently accessed pages as a reference". WYT? This way it’s clear that we’re taking inspiration from frequently accessed pages, review them and use them as a reference, but don’t follow them blindly.
What to Highlight will always be subjective so I don’t think we can find criteria to be followed strictly. I’d simply list the criteria defined above as examples or inspiration, but leave it open to any suggestion to change or set the highlights, as the writer sees fit.
The doc team (mostly Eleni) will monitor page changes in the wiki and especially changes to the landing pages (through the watch feature) to notice any change. I believe nothing bad will happen and we shouldn’t be worried (except for spam we get regularly but that’s not related to landing pages).
And as a best practice if someone wants to change some highlights, the best practice would be to ask on the #xwiki matrix channel or use a Change Request (which will be monitored by the doc team too - i.e. Eleni).
I agree it’s really subjective, and the idea should be to take inspiration from the Common Criteria listed above, so at least all contributors have the same reference.
I also agree with everyone being able to edit the Highlights and myself being the one to monitor.
+1 I agree that we shouldn’t try to enforce too many rules on this, just try to make sure we’re careful/knowledgeable when updating them.
It would be good to keep track of such responsibilities. It will need to be voted before updating the practices, but this could go into a Documentation Manager role for the project (https://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HSpecialProjectRoles). This way whenever the project contributors change we can avoid regressing on our documentation quality
