XWiki.org Documentation Reorganization (batch 1)

Development
1

Hi everyone,

I am a Documentation Engineer within the XWiki community, and I’m here to help improve the documentation. My goal is to make it more user-friendly, easier to navigate, and clearer for everyone who uses it. I already have a series of proposals, in collaboration with @vmassol for improvements with more to come in the near future. Community members are welcome to come forward with their own proposals and ideas.

In order to solve current issues with XWiki documentation like difficulty finding the right content for different readers (users, admins, developers), outdated information, and unclear navigation structure- I propose a structured reform based on 4 first steps: applying Diataxis, doc by target audience, track review status and introduce a Documentation XClass.

I will propose additional improvements later on, to make the XWiki documentation more consistent, navigable and user-friendly.

Proposal 1: Apply Diataxis

Diataxis is a way of thinking and organizing the documentation into 4 types, each with a distinct purpose:

  • Tutorials- learning-oriented experiences (lesson-like)
  • How-to guides- goal-oriented directions (recipe-like)
  • Reference- information-oriented technical description
  • Explanation- understanding-oriented discussion

Currently, many XWiki documentation pages have a mix of these types, which reduces clarity. We need to make sure that all our docs are of one of the 4 types and that they don’t do more (they should link to other pages for other types). This includes extension docs.

For example:

  • our tutorials are of type tutorial but they often go beyond and add “Reference” and “Explanation” in them
  • our FAQ entries and snippets.xwiki.org pages are actually “howto guides”
  • our Reference documentation often mixes Explanations

Proposal 2: Define Target Users

In addition to doc page types (diataxis), also differentiate the pages by target: users, admins, developers.

This distinction should be reflected in the navigation structure, the focus will be on User > Admin > Dev.

Proposal 3: Track Review Status

In order to track quality of each doc, each page should include:

  • The last reviewed date (when was the whole page reviewed against the doc best practice guide)
  • The name of the reviewer

These will be managed by properties in the Documentation XClass (see below)

Proposal 4: Documentation XClass

It should include the following fields:

  • Type (Tutorial, Howto, Reference, Explanation)
  • Target (User, Admin, Dev)
  • Last Reviewed Date
  • Last Reviewer

This proposal, along with the upcoming ones, supersedes the ideas outlined in this forum post.

4 Likes
2

Obviously +1 from me for all proposals :slight_smile:

1 Like
3

For reference:

How was this model picked? Is there alternative models of thought for documentation and what are the advantages of diataxis compared to them?

Overall I find diataxis interesting, and picking a clear knowledge model for our doc is definitely a big improvement.
+1 from me on this.

+1, I think it’s a large problem for our documentation today. Users cannot find what they are looking for because it’s often just a small line on a large page mostly for Admins or Devs. In some places we do apply target users (e.g. the main documentation at https://www.xwiki.org/xwiki/bin/view/Documentation/ ), but it’s not respected everywhere and I believe it creates a lot of confusion.

+1 , IMO for it to be useful, we need some kind of table that lists outdated documentations in a doc for documentation contributors, based on this status.
In order to provide a meaningful status, maybe it’d be good to count the number of major updates to the page since the last reviewed date?
This way, a “dead” documentation page will not ask for new reviews while one that gets updated often will need reviews regularly.

I think it’d also be interesting to make sure the actual content is also reviewed. Some pages contain info that are completely outdated. A review that’s purely based on the best practice guide would not catch it. Same problem for outdated screenshots, we try to update it when it’s too different from today’s UI but IMO some screenshot update status could be useful.

TLDR: I like the idea, but think we should leverage it more, we have a few quality improvements that should be done on documentation regularly that are not in the guidelines.

+1

Welcome to the community and thank you for starting this proposal!

Lucas C.

2 Likes
4

I’m not sure such a review would be that useful. I mean sure it’s nice to review that the documentation is formally consistent, but I have the feeling our documentation guidelines rarely change, and it would waste quite a lot of time to regularly review that all pages conform to them. What would be more important imho is to review that the documentation is still up-to-date, the screenshots show the latest version of the UI, the tutorial still works, …

Also, it’s not clear to me who would be allowed or expected to perform these reviews. At least on GitHub there seem to be users who review random pull requests and approve them - quite clearly without having any understanding of the actual change they review. How do we avoid that random users mark documentation as reviewed without reviewing anything?

1 Like
5

Thank you for bringing up these valid points!

You’re right that just checking if a page follows our best practice guide is not enough.
The idea is not only about formatting, but more about tracking when someone last confirmed the page is still useful and correct; indeed that the examples still work, screenshots reflect the current UI. (Just an idea but maybe we can even expand the review system to include different review types: technical accuracy, tutorial tested, updated screenshots etc? )

As for who would be allowed to mark a page as reviewed- that’s also a good point. Maybe we could limit this somehow by defining a clear role (e.g. “Doc reviewer”) to avoid random approvals.

1 Like
6

Note that up-to-date screenshots is part of the doc guidelines so reviewing the page against the guidelines means also checking the screenshots.

And checking that what is written is correct should also be in the doc guidelines (even if it’s obvious that the doc needs to be true).

So for me it’s definitely about checking the page against the doc guidelines/best practices.

Yes, we need to define this. I’m not too worried though as it’s not different than making changes to the content of a page (it’s actually less visible so less chances of spam). But we still need to decide whom we want to allow doing these reviews. Could be limited to committers + a “doc reviewers” group to start with. In any case, we don’t have an easy way to control that (except by coding an Event Listener to control it).

Thx

7

Thank you for the proposal Eleni, and +1 from me on all the proposals!

1 Like
8

Hi Eleni! :wave: :wave:

Thank you for working on this! :pray:
Your proposals look great, I agree with all of them on my side.

I did, however, want to offer a bit more resources (you may already be aware of some of them, but I doubt it would hurt to also have them linked here):

Again, thank you for working on this!!

2 Likes
9

Thx detailed proposals @elenicojocariu.

I’d say that Proposal 1, 3 & 4 have a typical subtext - restructure/reorganisation. Its implementation is complicated and may decrease the community’s contribution to documentation due to the revamped process.

Existing rules are apprehended, but the embedded process that must be followed rejects the desire to create a draft version of the enhanced document, which will include a new section. I try to modify the existing text to a more relevant one - in other words, I’m not saying that I don’t mind the guide rules, but avoid some of the actions in that procedure. That’s why, if new one will have even more requirements, I don’t know how it may improve documentations/guide’s process in best way.

I assume by presenting such questions we’re returning to the point that was raised in the forum and public room that there’s a thought to install Change request application and set it for the website, which may be a temporary solution or the best choice compared to the said proposals.

This one can be implemented or improved easily nowadays. However, based on personal use of XWiki and all knowledge. I’d highlight 2 users’ roles - Admin and Dev.

Unfortunately, the design and its content are outdated and require considerable modifications.

10

+1 for your proposal overall.

My only concern, and a problem I often have when writing documentation, is with determining precisely:

  • what is the target audience, because it’s not always easy, for me at least, to determine if some information is useful only for admins, or only for developers
  • what is the documentation type, because I have the feeling there is some overlapping between Tutorials and How-To guides, and between Reference and Explanation documentation

I scanned quickly https://diataxis.fr/, and I haven’t found a quick overview to explain the differences between these 4 categories.

For instance, regarding the first two, both can have steps, and you usually want to learn something because you want to do something with what you learn, so there is a more specific goal than “leaning”. So if you want to learn how to write a rendering macro, what should you look for, a tutorial or a how-to guide?

Regarding the last two types, I felt the need in the past to explain things in the reference documentation, i.e. to explain why it was done like this. Take for instance this section from the PDF Export Application reference documentation https://extensions.xwiki.org/xwiki/bin/view/Extension/PDF%20Export%20Application/#HGridsystem . The information is:

the default PDF template is redefining Bootstrap’s grid system to match the standard paper sizes used when printing

But I felt it was important to explain why it was done like this, so there’s also some explanation there. I take it that we’d have to move that explanation elsewhere?

Thanks,
Marius

11

All user doc is also useful for devs and admins. The point is that dev doc should not be needed for users nor admins and admin doc should not be needed for users.

What I understood:

  • How to = recipe, with steps. Helps do a real task in XWiki (for your work). Example: “Create an Application”
  • Tutorial = How to applied on an example. Doesn’t help you directly do a real task, it’s there to learn how to use something. Example: “Create a FAQ Application”.

For writing a rendering macro, it’s possible to have 2 docs:

  • One being a howto to explain how to write a rendering macro (step1: create a page and add an xobject, step 2, etc)
  • Another one being a tutorial about how to create a “hello world” rendering macro for example

In practice, my take is that 90% of our docs will be “howtos”.

Yes, the idea is to move the “why” in another doc and link it. The idea is that each doc type should be super focused on its goal and distract the reader the less. But ofc it should link to other places to learn more.

BTW I don’t think we’ll have a lot of Reference documentation. I believe we’ll find that most of our docs will be how to (when a new features comes up with a UI we’ll have howtos to explain how to use it + explanations for details). Sometimes, we’ll have reference doc but I don’t think we’ll do a lot as it’ll duplicate a bit the howtos. You need to think of Reference doc as a doc laid out as a table, with each row documenting an item.

Thanks

1 Like
12

Personally I suppose Devs ⊆ Admins ⊆ Users.
This means all devs are admins and all admins are users.
The first one is not always true, but I think it’s fair for expect devs to also look for some of the least technical documentation in the admin docs.

I guess the four categories are not related to the exact way you implement them but about the use of your documentation. The diataxis compass

In your example, you can have both.

A howto can also assume more knowledge of the subject from the user, meanwhile the tutorial is here to explain how things work for total newbies to the topic.

2 Likes
13

We’ll see down the line how it goes, but the low amount of tutorials could be an indicator of why it’s difficult for new or non-tech people to get into XWiki development :slight_smile:

14

I’ve struggled with that distinction too, especially since both tutorials and how-to guides have steps. For me, the key difference is what the reader really needs.
A tutorial shows you how to use a feature by walking you through an example. A how-to guide is more like a recipe that helps you get something useful done right away.
Actually, our FAQ entries and most pages on snippets.xwiki.org are how-to guides, because they’re all about helping you solve real problems quickly.

2 Likes
15

Eleni, Pauline and myself will come up with real life examples for the 4 types of docs. I think that will be the easiest way to understand the various types.

Note that we will definitely progress on our understanding of the various types, and in the quality of our docs, as we progress about using them.

5 Likes