This topic is about some improvements on the documentation structure:
Proposal 22: When to Use Landing Pages
Context: We have experimented landing pages on xwiki.org, and several structural improvements have been identified.
Use explanation pages instead of topic landing pages.
Current topic landing pages (e.g., Base, Page, Like, etc.) contain summaries, highlights, and a section with search and LD. In practice:
summaries are hard to maintain as they describe what’s below, while 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.
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.
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.
Not all pages have highlights. It’s optional. Only pages with lots of children to help readers find important pages.
Not all pages have children so that “Find More” section si not displayed on all pages (there’s a bug currently that we need to fix, where the section is displayed even when there’s no children page). But yes every page that displays a children LD will display a search too. That’s a good feature
Currently, the description of an explanation page is:
Explanations that answer the “why” behind XWiki’s behavior, helping regular users understand how things work and expand their knowledge.
This doesn’t fit to me with providing an overview of a topic. To me, the top page of a topic should provide an overview or introduction to a topic, and not explain the “why” behind XWiki’s behavior.
In the end, however, I don’t care how we name those pages, if they are “landing” or “explanation” pages. What I care about is that they provide an introduction to the topic that is provided by the pages below them.
+1 I can’t remember what was the reason we used a special type for landing pages. Was this discussed before or we just assumed we’d need it for technical reasons? I agree with the idea, but we need to make sure we don’t go against a previous discussion by changing this
+1
Small note on implementation: Find more about the current topic would be a bit better as Find more about ${pageTitle}. For Assistive Technology users, not relying on the context to give information (here the context is the “topic” which is contained in the pageTitle) is always nicer.
+1, navigation only pages do not need more or less than this
+0, I doubt it would mess a lot of people up but it shouldn’t be that useful now even for the documentation team.
+1 to using landing pages as broad explanations of the topic covered in the space.
The move to actual explanations pages sounds ok as well, though I probably do not have all the keys to evaluate how it’s impacting the navigation and listings.
I think there was a small misunderstanding in the proposal. The idea was not so much to replace Landing Pages with Explanation page but to remove the need for Landing Pages, i.e. all pages become documentation pages.
We already have lots of doc levels with container pages being of different types (explanations, howto, etc). Some example:
The idea is to generalize this to all pages, except for the following pages which would remain landing pages (and we won’t need to create more pages of this type):
It’s just that it’s very likely that top level container pages will be of type explanations, but it doesn’t have to be. But the general rule is that doc pages with children can be of any type.
Don’t you think that Find more about the current topic is a bit longish? WDYT of simply “Find more” or “More” but with the text line below modified, as in:
Note that if there are no highlights, the text would be: To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
Hi!
Indeed, the title of the heading Find more about the current topic is quite long. Currently, we already use More for pages that don’t have the landing page object attached (see: Change the Syntax for example). I would say it’s a better choice since it also aligns with what’s existing.
Re the layout, it looks clean and well organized. The suggestions for further reading /searching are right after the actual page content, which is great. Thanks!
