Future Directions (#20)

[ceford]

I wanted to write down my personal view of the best way forward for Joomla documentation. It needed to be long and illustrated so I wrote it as an article on my personal website. It has turned into an outline spec for a Joomla extension for managing documentation. I will probably take it to completion - a couple of months. It could be useful to someone even if Joomla takes another road. This coding hobby is addictive!

You might like to take a look:

https://jdocmanual.org/joomla-documentation-future-directions.html

The article may evolve as the work progresses. Feedback welcome.

[max123kl]

@ceford a fantastic, substantial piece of work. For the most parts, I agree with you.

In the short time I have had, I have not yet been able to read your explanations intensively, but the article contains some good ideas and these are worth developing further. Unfortunately, from a technical point of view, I have not yet understood how some steps can be taken.
But I am convinced that they can be realised. If possible, we should therefore try to get someone from core development to help with the process of implementation, at least in an advisory role.

My fear is that, as with Carlos' statement(#20), we will burden each other with endlessly long posts. For me as a foreign speaking person (probably Carlos feels the same way) it is very difficult not to lose the thread in such long posts.

You have set the marker [ToDo] in some paragraphs. My strong request is that we divide the text into smaller sections, as I did before. It would be a great help to me if I could comment on the individual points and ask questions in smaller posts.

What do you think about creating a collective issue with reference to your article, with a task list for the individual points/ToDo's to be clarified? Sub-issues can then be generated from this list, which can be worked through more easily.

[max123kl]

@ceford you say the following in the introduction of your text:

It is my belief that we should look no further than Joomla itself for a delivery and management system for Joomla documentation.

and in the following paragraph:

... that source text should be stored in a Git repository in Markdown format.

I fully agree with you on these two points. My question is more about how to realise this without always having to go the way via PRs on Github. You are right to say that not everyone will be willing to commit to this process. The two screenshots for editing the GFM source show a view from the backend of Joomla. This is certainly a solution worth considering for many contributors. However, they would need access to the backend or write permission in the frontend. I can only see the possibility of ensuring a comprehensible process via the workflow process. But that requires that someone will have the job of checking and also verifying all submitted changes. I don't know if we can do that with the number of helpers we have at the moment. Transparent tracking and resetting will certainly still require adjustments in extensions or in the core and should be combined with a VCS (), like Git.

Through a post by Hackwar on Mattermost, I learned about the Joomla framework, which I had not looked at before. Is it possible to use it to create an application for our purpose?

By the way: The Joomla Framework also needs a complete documentation, which so far exists only partially. This could become the fifth part of the manuals.

[carlitorweb]

In a perfect scenario, a custom application for a documentation need start as you saw, with the framework, not trough a CMS extension.

But again, we are not in that perfect scenario, and the implementation of this idea will mean in the short term another maintenance task, who maybe will not involve the initial developer of the application. So far, not good experiences happened with this type of approach.

And yes, submit documentation need have a little of review before publish, is one of the down points of mediawiki, and is something to have in the documentation.

[ceford]

I fully agree with you on these two points. My question is more about how to realise this without always having to go the way via PRs on Github. You are right to say that not everyone will be willing to commit to this process. The two screenshots for editing the GFM source show a view from the backend of Joomla. This is certainly a solution worth considering for many contributors. However, they would need access to the backend or write permission in the frontend. I can only see the possibility of ensuring a comprehensible process via the workflow process. But that requires that someone will have the job of checking and also verifying all submitted changes. I don't know if we can do that with the number of helpers we have at the moment. Transparent tracking and resetting will certainly still require adjustments in extensions or in the core and should be combined with a VCS (), like Git.

I think we learned something in recent days: GitHub is just as likely to be an obstacle to newcomers as MediaWiki. New helpers will be Joomla users. Best to use Joomla to let them help.

Backend/Frontend is nothing to worry about, other than that users need to register and login. I have two extensions that started as backend only but soon came to have a frontend too. This is my latest: https://jdocmanual.org/merged-pulls.html (select the Documentation Required / Yes filter). I started that a few weeks ago as a potential method of managing documentation requirements but left it when you guys seemed clearly GitHub oriented.

We already have to have someone vet changes in MediaWiki! Until marked for translation any changes are not set in the /en version of a document and are not available for translation. We can make the approval process super-easy in Joomla.

My ideas on how to do it all in Joomla are progressing rapidly. There is an English phrase: I have the bit between my teeth. Does that translate?

[ceford]

In a perfect scenario, a custom application for a documentation need start as you saw, with the framework, not trough a CMS extension.

Just over 20 years ago I used a python based framework named Zope in the days before Plone reached its first release. It went from version 1 to version 2 then stumbled on 3. I have a book entitled Zope 3! But that was eventually split off as a separate framework (Blue... something) and Plone stuck with Zope 2. I have looked at the Jooml framework several times - it is not well documented and some of its libraries are used in Joomla and some are overridden. I see no advantage in not using the Joomla CMS that comes out of the box.

But again, we are not in that perfect scenario, and the implementation of this idea will mean in the short term another maintenance task, who maybe will not involve the initial developer of the application. So far, not good experiences happened with this type of approach.

That is why I have set my sights on producing an extension that can handle any documentation. As a hobby coder, it suits me to spend my time doing the work. And like any artist, I am pleased if anyone finds it attractive and/or useful.

And yes, submit documentation need have a little of review before publish, is one of the down points of mediawiki, and is something to have in the documentation.

I submitted something for the Programmers Manual (Docusaurus). I found it tedious and very frustrating. Even fixing a typo could take months. I also tried out Docusaurs and built a Programmers Manual. Even when you have created the content the deployment reveals bugs arising from content. You can find it here: https://docus.jdocmanual.org/docs/intro

If we are short of people with expertise we should not be using yet another different platform. We can do much better with Joomla.

[carlitorweb]

That is why I have set my sights on producing an extension that can handle any documentation. As a hobby coder, it suits me to spend my time doing the work. And like any artist, I am pleased if anyone finds it attractive and/or useful.

Nothing I have against this. Is good you found an inspiration for your hobby.