You can help to get better Joomla user documentation!

We want to improve the user documentation. At the moment we are focussing on the content: 

• To get the user documentation complete.
• To better guide new users of Joomla.

A few years ago Cliff Ford rearranged the user documentation from the wiki into JDocManual. In the beginning of this year we copied the content of that user manual to our  “sandbox-site”: docs-core.sandbox.joomla.org. We are rearranging the alphabetical structure, to get a more logical flow in which you can gradually learn more about Joomla. With the focus on people who are new to Joomla. And we are identifying the missing parts.

You can help with three things:

• Anybody can help by adding new content, especially beginner tutorials. We have a list you can work from. This can be incidentally, doing something in a lost hour.
• We need a few people who want to more structurally dedicate some time on documentation, processing the contributed results, and training to improve technical writing skills and discussing placement of content as a team.
• And we need a few people to help with some implementation and maintenance.

Adding new content

User documentation should not only be made by programmers. We need users of Joomla to contribute in order to make it clear for other, non-technical users. And here is the nice thing: everybody can help! If you are new to Joomla, then that is very valuable, because you can better see if the documentation is understandable for new users. 

We try to make contributions as easy as possible, by splitting the initial contribution and the further processing. When adding content to the documentation, you don’t have to worry about where to place it, or technical details. You can simply write your contribution with Joomla. We use front-end editing, so just type your article as you would do with any other article in Joomla. Then in the next stage others will further process your contribution.

How to contribute by adding new content?

1. Create an account on the sandbox site. Some people have had trouble with the confirmation email not being sent; we are working on it. Don’t worry about it, it will be alright after the next step. Tip: if you have a Github account and use the same username for this account, you can later login with Github.
2. Come to the Documentation Suggestions channel on Mattermost and ask for permission to write. Let us know the login-name you used.
3. After you’ve got author rights, you can log in.
4. Look at the todo-list for things that are needed in the documentation. It is on GitHub: github.com/joomla/documentation/issues. If you have a GitHub account, you can indicate on the issue that you are working on it, to avoid double work. Any questions or discussions about the topic you are documenting can be held there too. If you have no GitHub-account yet just let us know on the Documentation Suggestions channel on Mattermost.
5. Start writing! Nobody sees your draft until you submit it for review. You don't have to worry about the exact place where your contribution is placed: that is being taken care of by the Documentation Curators.

As you can see, we use Github to communicate about the documentation issues. Without a Github account you can only read those issues and discussions, not participate in it. It is not difficult to create a Github account and that is really handy for different kinds of contributions to Joomla, for instance when you want to help with testing bug fixes. 

For the content we now focus on the English version. After that we will do translations automatically (with a human review). We’ll use Cliff’s experience to do that with JDocManual. But that’s for later. For now we are not looking for translators of the documentation.

If you write something about a topic, try it out yourself first. You can use the experience of doing it wrong at first: not only you can learn from those mistakes, but others too. You can show others the way to do it.

Processing contributions, guarding structure and quality

We don’t want to bother the initial contributors too much with details like where to place things in the user guides, or polishing the last bits before publishing.The idea is that some volunteers specialise in that and will process the  contributions. A team of “Documentation Curators”. We provide training and let you grow into this role. This small team will guard the structure and get the content tiptop. In a short bi-weekly meeting we coordinate the efforts.

At the moment we are urgently looking for two more people who want to do this task! Who can spend about one hour per week on this? We get some contributions now, but don’t have enough people to process them. So, this is really a bottleneck. You can improve your technical writing skills and work with some other nice people on a practical and much needed product: good user guides. Would be great to proudly present the result with the release of Joomla 6 in October. Please contact me, Herman Peeren, on Mattermost. Thanks for considering!

Implementation and maintenance

The last years a lot of time has been spent on figuring out what the best way is to implement the documentation. Now we want to put emphasis on improving the content, as you saw above. For the user documentation we want to do that as much as possible in Joomla itself, also to make contributions as easy as possible. But some practical things have to be done for that too. That’s why for the coming months we are looking for people to help with enhancements of the following Joomla features:

• Workflow: we use the Joomla workflow. Some adjustments have to be made to make it really workable, like sending a message of a transition to the original author, making a plugin to change visibility of an article and automating some properties when placing an article. The same things are wanted for the Magazine and for the Enhanced Guided Tours website, so we are forming a group to get this done.
• Versioning: we use the Joomla versioning, but some things can be improved, like the screen displaying the difference between versions. We also have some plans to use the Github versioning in Joomla.
• Website: we need a webmaster to do the regular maintenance, like Joomla updates and backups. But also some CSS and/or overrides to get menus better displayed in the used joomla.org template.

These are concrete projects that we want to accomplish in the coming months. So it is overseeable, not something that will slurp your time in the long run. Who can help with this?