XWiki.org Documentation Reorganization (batch 6)

Development
,
1

In addition to the other proposals, we (@vmassol, @paulinebessoles and myself) propose to have a fixed structure for each documentation page. This is achievable by having stable headings configured by default.

Proposal 11: Heading structure for Doc Pages

Names we suggest for the headings:

  • 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.
  • Provide Doc Templates for each doc type.
  • Have a TOC in the Templates:
{{box cssClass="floatinginfobox" title="**Contents**"}}
{{toc/}}
{{/box}}

For example, this is how the Change the Syntax page would look like.

Related

1 Like
2

If we’re enforcing a heading structure on pages, I think it’d be great to make sure we only use one H1.

This means that we use only H2 and lower in the page content, the only H1 is the page title. This ends up in a cleaner heading tree.

image
image2403Ă—1275 306 KB

On this screenshot, we can see on the left that the heading tree does not reflect the actual content organization.

Note that we already removed all the extra H1s from the XWiki UI.

Having a clear heading tree is very helpful for assistive technology users (e.g. screen reader users can navigate quickly to the section they are looking for using headings). XWiki cannot enforce to not use H1 in content, but as a community we can encourage it, and using it in our doc would be a great example (in addition to making our doc more accessible).

From a quick look at this proposal, it seems that making the headings use H2 instead of H1 is quite easy and does not create extra work/make things any more difficult, so I believe it’d make sense to do it with this proposal if it’s accepted.

It feels like breaking the principle of diataxis to put two kinds of content in the same doc (e.g. FAQ on a reference page). I think it would be good to define what is a “small explanation” and set a rule for when to move this explanation into a full fledged page. I believe that if there’s no rule, I’ll just add a couple lines in the explanation to document the changes I made to the feature, but never bother to create a new doc.

Wouldn’t it make sense to put 3 and 4 together? All children pages is just an automated way to highlight some related pages. I’m not sure we need separate headings for what’s functionally very similar. It would make sense to make two lists in there to differentiate the handpicked pages from the children though.

Maybe a rule to limit the size of the FAQ section could be when you feel it needs a heading, it needs to be its own page.

+1, on the old documentation, I feel like I added a ToC on most of the docs I wrote and often wonder why some documents don’t have one. The only kind of doc that doesn’t need a ToC is a doc without headings, but this proposal has a minimum of two headings in each doc so it would always make sense to have a ToC.

Thanks for spending time on these improvements!
Lucas C.

3

Great point! I didn’t know about it until now, thanks for bringing this up! Indeed, if the proposal is accepted it shouldn’t be a problem to use H2 for the default headings.

4

Hello. We don’t use H1 or H2, we use headings. And we should definitely use level 1 headings. It would be a bug otherwise. What Lucas is mentioning doesn’t affect this proposal. It’s some internal decision to agree how level 1 headings are implemented in XWiki. It affects all pages. Thx

5

The idea is that short and very specific info boxes can be transformed in troubleshooting questions. For example, a user is following the steps in a Howto guide, but doesn’t see something in the UI or something unexpected appears that makes it hard to continue. In this case, the doc writer can mention the reason for the issue under a “FAQ” heading and link the user to another documentation page for more details and explanation.

Having a “FAQ” section supports Diataxis approach because instead of adding info boxes after each step saying stuff like “If you can’t find this, it’s because…” and interrupt the user, we separate those exceptions from the main steps. This way only users who will encounter the problem will go to the “FAQ” section and others can follow the steps without distractions. This is a better way to guide users to additional documentation, not to include full explanations in the same page.

6

I’m not sure it’s possible to combine them, from a technical point of view. The children pages are listed automatically, while related pages need to be added manually since they don’t have a direct structural relationship to the main page. Thanks!

7

Hello! I agree with Lucas when he says we shouldn’t have several level 1 headings in a same page, as it’s a big problem for accessibility.
Only the page title should be heading 1, if we want to follow the guidelines of RGAA and WCAG.

Hello. We don’t use H1 or H2, we use headings. And we should definitely use level 1 headings. It would be a bug otherwise. What Lucas is mentioning doesn’t affect this proposal. It’s some internal decision to agree how level 1 headings are implemented in XWiki. It affects all pages. Thx

So I’m not sure if I understand your comment, are you saying we shouldn’t follow those guidelines? Or that we should solve this problem in another way (and in another proposal I guess)?

Thank you!

8

Hello, in XWiki you’re supposed to use a heading 1 (ie = in XWiki syntax) for your top level headings in page content. If you don’t and use a level 2 heading, then you’re making a mistake. You can see it in the TOC of a page for example.

How XWiki translates the headings into HTML is an implementation detail that needs to be addressed in xwiki’s rendering code. Certainly not at the user’s level when authoring pages. So addressing duplicate H1 is independent of this proposal.

Thanks

9

Since this proposal, the documentation guide already explicitly mentions that only h2 level and lower should be used, so not using h1 is already an agreed practice. If you believe we should change this again, I think you should open a new proposal or vote.

10

Hi Michael, thx for pointer. I’ve definitely missed this proposal since I’d have been very strongly -1 about it (as it has been discussed in the past). Let me reply there + start a proposal.

11

I agree with you. We need to find a way so that doc writers don’t add too much in page FAQ sections. We really hesitated about being ultra strict and always creating pages (and then having these pages appear in the Related or More sections, and allowing page titles to be formulated as questions, such as “Why isn’t there an Edit button visible?”). We can still choose this solution if what we proposed doesn’t work well (see below for the experiment).

Re " troubleshooting questions, small and specific explanations, etc", it’s 1 or 2 sentences at most for me. Beyond that, it probably deserves its own page.

I propose that we try it on the refactoring of https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/PageEditing that we’re doing, i.e. on the pages at https://www.xwiki.org/xwiki/bin/view/XS/XWikiStandardFlavor/, and see what it looks like.

We’ll post the result when we have progressed enough.

Thx!

1 Like
12

I’ve worked on this yesterday and here’s the implementation for proposal 11:

  • Modify the Documentation Class to add 2 new properties:
    • A faq textarea property
    • A related textarea property
  • Create a DocumentClassSheet which will be bound to the class

The idea is to automatically generate the headings + toc + the “More” LD. This will provide:

  • Consistency
  • Hints about how to fill the FAQ and Related sections

I’ve done a POC yesterday:

WDYT?

Thx

PS: I can think of 2 cons ATM but IMO they’re not strong enough to not do it vs the advantages:

  1. No RT ATM on the content editing part
  2. A bit more CPU intensive and slower than a plain doc page since there’s some velocity executed.
1 Like