Joomla documentation is plentiful and easy for anyone to contribute to. Over the years the Joomla Documentation Wiki has grown considerably, which in itself is good, but also brings challenges.

 It lacks structure, it's hard to search, it contains a lot of outdated articles, and translating the documentation is not as straightforward as it should be. So it's time to reconsider our documentation tools. What if we could have a Joomla based solution for our documentation?

Jdocmanual is a custom component designed as a Proof of Concept for ease of use, ease of contribution, ease of translation and ease of management. It brings together Joomla articles in Manual format as seen in many other software documentation projects: Index of Articles to the left, Article text in the centre and Article Contents to the right. That presentation is the easy part! This article mostly covers how the other easy requirements are met in Jdocmanual. It is intended to contribute to a discussion on the future of Joomla documentation.

You can try the public view yourself: https://jdocmanual.org. This is what it looks like in the Administrator view:

The Site view is similar but without the left menu. A user may choose any of the available manuals and display the Index and/or Content in any of the available languages.

Source Data

The articles for Jdocmanual have been selected from docs.joomla.org, which is the MediaWiki installation used for Joomla documentation. Only articles relevant for Joomla 4 have been included and each has been converted to GitHub Flavoured Markdown. The articles have been organised into separate Manuals for different user groups: User, Developer, Documenter and Help. Others can be added, for example Tutorials selected from the Joomla Community Magazine may come later.

Updating data

Jdocmanual can have multiple contributors in two User Groups: a JDM Author may create a personal copy of an article for editing purposes; a JDM Publisher may commit changes created by a JDM Author (JDM is used here to indicate separate user groups from Joomla default Author and Publisher). A Publisher also has Author permissions. The list of articles available is always based on the source English list. This is a screenshot of the article list with a language other than English selected:

The ticks in the Translated column indicate that this particular article has been translated into the selected language. Those without a tick have yet to be translated. If English is selected this column is not displayed. In the Status column, Stashes: 1 indicates that a user has created a personal stash of that article to work on. The yellow New Stash buttons indicate that I can make my own personal stash of that article to work on. The green Edit Stash button indicates that I have already created a personal stash of that article.

New Pages must be created in English so a New button only appears in the Toolbar when English is selected. Also, new pages cannot appear in the Pages list because they only exist as stashes until committed. So the New Pages tab shows a list of any new pages in preparation.

My Stashes is a tab used to display a list of any stashes I have created to work on.

Pull Requests is a tab seen only by users in the JDM Publisher group. The list includes all pull requests by all users. The links in this list opens the same Stash Edit form used by Authors but it has an extra Toolbar button labelled Commit.

Editing Content

The following screenshots show selected tabs from the stash edit form. The fields in the Details tab are mostly prefilled from data on the page being edited. The Display Title is the only field that can be changed, except for a completely new English article where more fields must be filled before saving.

The Stash tab is where editing of content occurs. If the page is a translation the English version is displayed in a read-only text area to the left. If the page is an English version the edit area fills the whole page. Editing requires familiarity with Markdown syntax.

If you need to know what has changed in the original English version since the last update you can look at the English Diff tab:

The Source tab shows the current source of the Stash you are working on. The Diff tab shows the difference between your Stash and the Source. Before making any changes this will be empty because there are no differences to show.

The Preview tab shows a HTML rendering of your Stash. The Comments tab is for entry of a Commit message and feedback on any Pull Request.

Pull Requests

When a Stash is ready to replace the original content a click on the Pull Request button makes it visible to all the JDM Publishers. Anyone in that group can inspect the Stash using exactly the same form. If it is acceptable, a click on the Commit button, which appears in the Toolbar when a Pull Request is made, is enough to stage and merge the changes into the original article. The result is visible immediately.

Ease of Use

Is it easy to maintain? The answer is probably Yes and No. If I am editing the data myself with a few trusted friends then I guess the answer is yes. If there are dozens or hundreds of contributors in the Author Group, processing all the pull requests could become a challenge for a small team.

Help Proxy

The Joomla Help Pages are delivered by a proxy server. The url is in your Joomla installtion configuration.php file:

Where {major} and {minor} are replaced by your Joomla installation values, the {keyref} value is set in the Administrator page invoking a Help page and {langcode} is the two-letter code for whatever language your Administrator template is using, for example en or de.

In practice, we do not maintain different Help pages for different minor versions of Joomla. And updating Help pages when migrating from one major version of Joomla to the next is a significant problem. About 200 original English pages have to be copied and re-translated even though any changes may be minor.

All of this is much easier to do with Jdocmanual. If you are testing Joomla 5 you can change the domain in your configuration.php file to https://jdocmanual.org/ and expect to see the Joomla 4  and Joomla 5 Help pages in English or your own language.

Menus

In Jdocmanual the order in which items appear in the article index to the left of the article content is independent of the order in which the items appear in the list of source files. That is achieved with a menu list - a text file containing the list of articles in the desired order. This is very easy to edit by cut and paste to move an item. This is much easier than the drag and drop method used for Joomla menus. The menu order is language independent so there is only one menu for each manual. Users can make their own stash copy of the menu, change it and then make a pull request to have it replace the existing menu. The menu stash edit form has tabs similar to the article stash edit form:

Utilities

The other items in the Jdocmanual Administrator menu are used to manage languages, to translate menu headings and to manage manuals.

Future Development

Development of Jdocmanual has focussed on functionality. Little effort has gone into appearance other than that offered by the default Cassiopeia and Atum templates. Suggestions and alternative style sheets would be welcome!

Coding

Jdocmanual was developed as a proof of concept. Under the hood some of the code needs to be improved: libraries for handling markdown to html conversion have been included within the component itself rather than within the Joomla libraries folder; there are probably better ways of implementing git commands, for example by using the Joomla GitHub library; and more. Comments and suggestions are welcome.

Content Revision

In processing and checking MediaWiki articles I came to the conclusion that there are too many unnecessary internal links. With a good index, as in Jdocmanual, many links can be left out without affecting the value of the article. This leads to a better user experience. So far precious little attention has been given to the actual content of the articles appearing in Jdocmanual.

I think the next important task is to update content, merge similar items and incorporate new content from other sources, such as the Community Magazine.

Conclusion

If you want to try it yourself you can get the code and data here:

Code: https://github.com/ceford/j4xdemos-com-jdocmanual-v2.git

Data: https://github.com/ceford/j4xdemos-data-jdocmanual.git

Pay heed to the README.md files. Setup requires more than simple installation of the component!

If you would like to participate in further development of the Jdocmanual code please feel free to make a pull request.