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