Hello!
Some common user feedback in the latest years about XWiki is about the quality of the documentation. Unfortunately it seems like the state of the documentation as things are going is not as good as it should/could be.
In order to improve documentation, it could be good to let users know they are welcome to contribute to it. We already have a paragraph about this in our documentation at https://dev.xwiki.org/xwiki/bin/view/Community/Contributing#HDocumentation, but I’m pretty sure almost none of the XWiki users ever read it.
My idea is to add a Panel on xwiki.org to highlight contributing to documentation. Even without any additional incentive, I hope increasing visibility will increase community participation here.
The panel would be at the orange square position on all pages with Panels activated (we can discuss the exact order of the panels later in live chat, it’s a secondary topic IMO).
The content of the Panel should be pretty simple.
Option A:
Title: Community driven documentation
Text:
XWiki documentation is written and maintained by the community. Any contribution to improve it is welcome
Check out How to contribute to our documentation and start helping out the community!
Option B:
Panel is only shown to non logged in users
Title: Community driven documentation
Text:
XWiki documentation is written and maintained by the community. Any contribution to improve it is welcome Register and start helping out the community!
The Register is a button redirecting to the Registration page.
Option C:
Option B when the user is not logged in and Option A when the user is logged in
IMO option C is the best, it’s a bit more complex but it’s more tailored to the user situation and provides the most visibility to that aspect of the community we want to highlight.
Do you agree with adding such a panel to xwiki.org? What option would you rather see implemented if the change is approved by the community? Is there anything you’d rather change in the wording of those panel proposals?
I’m +0 as I’m pretty sure that the reason why people don’t contribute more is not that they don’t know that they can but that most people don’t want to break things and don’t know the overall doc structure.
We do have contributions every week to the doc or minor changes. And we’re already pretty good on the doc for each feature/change (it’s even in our process to be able to release!). Where we’re less good is the general structure of the doc, updated screenshots, clean up of old stuff, etc. ie stuff that are hard to conrtibute to if you’re not an expert.
In addition, people are usually afraid to make mistakes.
Moreover, people who don’t find the doc good are usually those who don’t contribute and have no incentive to do so.
So while we could add this panel, IMO it only bloats the web site, and is duplication for the contributing guide (where anyone who wants to contribute would go for sure).
IMO something that could help a little bit (but not much, don’t get overcarried :)) is adding the CR extension to xwiki.org:
It makes it easier to contribute by NOT requiring to create an account (this is a deal breaker for people who just want to fix a typo or do some small change)
It would allow people to propose changes and not be afraid of breaking stuff. We’ve discussed it countless times but we still need to fix one issue before we can use it on xwiki.org
Another idea (but it also wouldn’t change much IMO), is to implement gamification and give points to contributions (doc update being a contribution) and with the points grant rewards. I made a proposal several years ago and even implemented a POC during a hackathon but it’s a lot of work, and in the end I don’t believe it’ll change anything substantially.
My personal view, is that documentation is a difficult topic, there’s not enough incentive for people to contribute to it substantially (not more than contributing to coding). The reason why translations work is because people get incentives: they get their wiki in their language and they need it. Improving the doc means figuring out the answer to what you’re looking for and when you have the answer, the incentive to contribute it back is lower. Some people will do it but that’s not the majority.
I agree with Vincent. Moreover, another thing that might help is to provide an easy way for an unregistered user on xwiki.org to report: missing, incomplete or unclear documentation. Seeing multiple users complain about the same documentation topic is a good incentive for us, developers, and others as well, to add or improve the related documentation.
We could also try to look at the (Solr) search queries performed on xwiki.org and try to extract from there what the users are looking for most often. I suspect that most XWiki (simple) users go to xwiki.org for documentation, and what they search for could indicate what XWiki features are not clear / simple enough.
We also have advanced users that do scripting on top of XWiki, and they look for API documentation. On this area we’re pretty bad, and we can’t expect much contribution from outside. There’s no comparison for instance between https://www.xwiki.org/xwiki/bin/view/ScriptingDocumentation/ and API documentation | CKEditor 4 API docs (just an example that I used recently). But again, it would be good to know which topics are more important so that we can focus our limited resources.
Now I remember a recent discussion (not sure where but probably on xwiki) with @MichaelHamann and others who were not convinced that using the Change Request app was the right solution. If it doesn’t already exist, we need to bring that discussion to the forum to decide what we want to do.
