Getting started about j4.docs

[ceford]

I am afraid I strongly disagree with almost everything in this document!

We will start our journey from the Help screens project. This documentation have top priority between all. Before making the follow information "official", I wanted to consult with you for get a feedback.

Please see: https://github.com/ceford/J4.docs/tree/help/manuals/help - Help screens in English, German, ... It takes me about 10 minutes to do the conversion. This is just a demonstration that I need to refer to later.

1. We have not defined which platform will be used for the new documentation, but It is clear that we will not continue using Mediawiki. Docusaurus look as a good candidate, but still not all the few peoples involve and with interested in helping, totally agree about it. **One of the important things for the management of this documentation, is the ability to reuse created documents. In mediawiki it is handled with Chunks, here they would be .md files**

MediaWiki will continue for a long time to support older Joomla versions. Docusaurus is a terrible choice. Under the hood it is a dogs dinner. It is difficult to manage and binds you in to a particular layout. For this and other reasons I would prefer Joomla.

   _But while we look for it, we can start to migrate the Help screens content._

Pretty much done: see above.

2. The new format for the Help content will be **Markdown**. It is a global format which allows us flexibility when _choosing how we are going to visualize it_.

You make this sound as though Markdown is something new. MediaWiki uses Markdown. It is a different flavour from GitHub Markdown which is a subset of CommonMark, probably the nearest there is to a standard, We are just changing flavours..

3. I will ask for a independient repository for Help screens. I think the user/administrator documentation not need be in the same place as the Help screens, because thinking loud, even [Github Pages](https://pages.github.com/) is enough to display this Help documentation, and the proxy of the help buttons can fetch easy these pages or the .md files. I think separating this documentation gives us more flexibility in it.

We do not need an independent repo for help screens. You only need that if you are going to bind the content to the delivery as in Docusaurus.

4. The images used in the help screens will be located in a folder of name `assets` in the same path than the file being viewed. The images will follow some guidlines already defined in [Image Naming Guidelines](https://docs.joomla.org/JDOC:Image_naming_guidelines). A updated images guidelines will be hosted in the Wiki tab of the repository.

If you put the images in the same place as the text then anyone who forks or clones the repo will need to get the images too. That could end up being gigabytes. Images need to be on the delivery server. Not GitHub.

5. We will follow the same pattern so far in the current Help screens, about the amount of image to use. @ceford did a good job in this and I agree with him, while less image we need use, the better for the Help screens.

6. We will take care of the multilingual aspect of the help screens. However, as the procedure for this is directly related to the platform that we are going to use to display the help screens, for now we will focus in the english version. And to be realistic, we are too few now to think that we can also do the documentation in another language. So for the moment, it will only be a plan to be achieved in the future, if we manage to get the documentation on track.

Focus on English is what the Programmer Manual has done - with a vague promise that provision for translation may be provided later. We used to call that vapour ware. I think we should take translation seriously at the outset. We can't just discard what translations have been done already.

7. Help screens have links pointing to other help screens. To facilitate our work as much as possible, once the structure of this documentation is defined, we will begin to document from the lower levels, in this way we will be able to relate the Help screens once we reach higher levels in the structure.

Internal links are a real pain for conversion. I don't have a solution, other than to remove them completely. External links are no problem.

   Also, we will rely on a Kanban Board (Github Project) where we will enter the links that could not be completed in the document that is being migrated. In this way we can take into account which links to complete as we progress.

I don't know anything about KanBan - is this going to put off people we want to recruit to do documentation and/or translation?

8. It is necessary to attend the new entries in the documentation of the Help screens. I will ask for configure (if is possible) the joomla-bot, so that once a PR is marked with the label "Documentation required" an entry is created in the Help screen repository with the PR. From here, we will have to update mediawiki and the new documentation if it is already created.

It is easy enough to list all PRs that have Documentation required flags. There is no good reason to restrict that to Help screens.

9. We will seek to promote the repository to earn contributions. We will accept PR in the repository with contributions to the migration process.

I don't think we should manage documentation with GitHub at all. There are too many problems, especially for newcomers. I think we should do it with Joomla.

10. The feedback will be handled in the Issue tab of the repository. For example, a good feedback is to see what they think about which platform we should use for the Help screens.

One piece of feedback to grapple with: some say the Help screens are just a statement of the obvious that don't actually provide mush help and are largely ignored. I think the new Inline Help is great. Maybe Help needs a rethink.

And finally on the following structure:

It is too complicated and too targeted towards a deliver system. I tried out an index that was in logical order (like below) and another with largely alphabet order of first folder and then priority order of content. Both Martijn and I preferred the latter. You can see it here: https://docs.joomla.org/J4.x:Joomla_4_User_Manual_Index

I have four manuals in mind: Help, User, Developer, Documenter - based on existing content we should have two tasks:

1. Document upcoming changes related to Joomla code updates in Mediwiki
2. Design a better system for contribution and delivery - in my opinion that would be in Joomla.

All comments with the best intentions! Cliff

Structure of the documentation

Each Help screen is located on specific views and this views have a defined path to it. I think the expected behavior would be to define a structure similar to this path. So I propose the following:

├── Components
│   ├── Banners
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── Contacts
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── News Feeds
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── Smart Search
│   │   ├── MainView.md
│   │   ├── edit.md
│   ├── Tags
│   │   ├── MainView.md
│   │   ├── Edit.md
├── Modules
│   ├── Site modules
│   │   ├── MainView.md
│   │   ├── ModuleNameEdit.md
│   ├── Administrator modules
│   │   ├── MainView.md
│   │   ├── ModuleNameEdit.md
├── Plugins
│   ├── MainView.md
│   ├── PluginNameEdit.md
├── Content
│   ├── Articles.md
│   ├── ArticlesEdit.md
│   ├── FeaturedArticles.md
│   ├── Media
│   │   ├── MainView.md
├── Categories
│   ├── MainView.md
│   ├── CategoryEdit.md
├── Fields
│   ├── Fields.md
│   ├── FieldsGoup.md
│   ├── FieldsEdit.md
├── Users
│   ├── Manage
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── Groups
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── AccessLevels
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── UsersNote
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── Privacy
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── MassEmailUsers.md
│   ├── Messaging.md
├── Menu
│   ├── Menus.md
│   ├── MenuItems.md
│   ├── Edit.md
├── Configuration
│   ├── ConfigurationExtensionName.md
│   ├── Global.md
├── Install
│   ├── Extensions.md
│   ├── Discover.md
│   ├── Language.md
├── Maintenance
│   ├── ClearCache.md
│   ├── Database.md
│   ├── GlobalCheckIn.md
│   ├── Warnings.md
│   ├── InstallationMessages.md
│   ├── SystemInformation.md
├── Languages
│   ├── Languages.md
│   ├── ContentLanguages.md
│   ├── LanguageOverride.md
├── Manage
│   ├── Redirects
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── ScheduledTasks
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── Extensions.md
├── Update
│   ├── Joomla.md
│   ├── Extensions.md
│   ├── UpdateSites.md
├── Templates
│   ├── TemplatesStyles
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── Templates
│   │   ├── MainView.md
│   │   ├── Edit.md
│   ├── MailTemplates.md

[max123kl]

Hi folks
please, that's not a competition who's writing the most large posts ;-)
I suggest we pick one point after the other and try to resolve step by step.
Can we agree in that?

[ceford]

Hi folks please, that's not a competition who's writing the most large posts ;-) I suggest we pick one point after the other and try to resolve step by step. Can we agree in that?

I did think of breaking up my response into individual items. Would this be better in Discussions? I could start one on why/why not to use GitHub. Actually, I would prefer to demonstrate why not with code rather than talk. But that could take a while.

[max123kl]

@ceford I have so many questions about the statement of Carlos as well. I need a while too.
As you may not know. Carlos and me got access to a new private repo on GH/joomla. I'm just looking for a possibility to invite you and Alan to take part on it.
I believe this discussion should be continued there.

[carlitorweb]

I'm just looking for a possibility to invite you and Alan to take part on it.

@max123kl for this @ceford need create a account at https://volunteers.joomla.org/ , and then I can add list him in the https://volunteers.joomla.org/teams/documentation-team . After that, is when we can ask to Benjamin to add @ceford to the repo. Is the way of do it.

[max123kl]

Cliff is already listed as joomler on volunteer portal - I think he has an account.
@alann60 do you have an account?

[carlitorweb]

All comments with the best intentions!

@ceford never worry about this, we just sharing our opinions.

First of all:

If you put the images in the same place as the text then anyone who forks or clones the repo will need to get the images too.

This is a strong and valid point.

MediaWiki will continue for a long time to support older Joomla versions.

MediaWiki and the current docs will stay as a historic archive.

Docusaurus is a terrible choice. Under the hood it is a dogs dinner. It is difficult to manage and binds you in to a particular layout. For this and other reasons I would prefer Joomla.

The implementation with Joomla, you have only the code, and we cant rely our work on that. Also, please notice you may not saying the current situation. There is a lack of hands for do anything inside the organization. A custom implementation will need a lot of more time, and also in the long term, will need "someone" take care of implementation and maintenance. Have in mind, maybe we will not be contributing in a near future. Or maybe in a near future we have 20 more hands supporting the documentation. But we need think using what we have now, is how I see it.

Never said Docusaurus is the one to use, just wrote is a candidate. Rely on external software is more real in our current situation. It eliminates the custom implementation, and we can focus more on the output of the content.

You make this sound as though Markdown is something new. MediaWiki uses Markdown. It is a different flavour from GitHub Markdown which is a subset of CommonMark, probably the nearest there is to a standard, We are just changing flavours..

Sorry is not just Github markdown, github just use what others use. Markdown is not new, but for sure the one of Mediawiki is totally different.
Based on facts, one of the reasons the documentation do not have more contributions, is for this format. We cant stick with mediawiki, not matter what we try do there. I think we already talked a lot of why we cant follow mediawiki.

Focus on English is what the Programmer Manual has done - with a vague promise that provision for translation may be provided later. We used to call that vapour ware.

Developer manual what need is contributions, that is all. For what migrate the content in other language if you do not have yet the main one.

I think we should take translation seriously at the outset. We can't just discard what translations have been done already.

I not discaring the translations, I just working with our real status, and what we can do with the persons we have now. And for sure, migrate the content of others languages is not possible for us in the short term.

it is easy enough to list all PRs that have Documentation required flags. There is no good reason to restrict that to Help screens.

I kown is easy. But again, what we can do with the current people we have now? I think we can focus in the short term only in the help screens for now.

I don't think we should manage documentation with GitHub at all. There are too many problems, especially for newcomers.

We are not getting newcomers, as already wrote, mediawiki do not help on this important goal. Git versioning and the workflow you can set up make it a very acceptable solution.

some say the Help screens are just a statement of the obvious that don't actually provide mush help and are largely ignored. I think the new Inline Help is great. Maybe Help needs a rethink.

That is something we cant decide. All we can do is raise this feedback to the leadership, and see what they think about.

It is too complicated and too targeted towards a deliver system. I tried out an index that was in logical order (like below) and another with largely alphabet order of first folder and then priority order of content.

I not agree in this really. I expect find a page of the Help screens with a similar route to where I found it in the administration. I think is more intuitive.

[ceford]

I have a Volunteers account. bembelimen offered to put me on the team but I never responded. I just asked hime to go ahead.

[carlitorweb]

@ceford I added you. I will contact Bejamin for give access to the private repo and we will continue the talk there

[max123kl]

Sorry for my late reply - but as we say in Germany: "Ein alter Mann ist kein D-Zug", which can be translated into English as: "An old man is not a high-speed-train". ;-)

I am now, here in this thread for the last time, commenting on the individual positions in Carlos' statement and Cliff's response (it should be separated by topic). I think the kind of discussion has started now will only lead to a wild exchange of arguments and will never be able to reach an agreement if we always deal with all the points at the same time. It is just an embarrassment.

Publicly, therefore, I will say nothing more than my following statement. On the other hand, we are dependent on suggestions from the community in order to find the broadest possible basis for decision-making. That's why I have and will keep referring to this repo in my Mattermost posts and solicit participation (@ceford you might do the same in the forum).

on point 1 + 2)
The Jdoc wiki, in its current form, is not satisfying. Switching rigorously from MediaWiki markup to Markdown markup will not solve any of the problems. There are pros and cons for both variants. The switch to Docsaurus (or to another system like "ReadtheDocs") will not be a decision made by the Documentation Team - it will need the approval of the Production Department and perhaps the Board of Directors. I see the task of our current group as preparing the decision and coming up with a proposal with good arguments and submitting it to the boards. This is not and will never work as a one-man show. On the contrary, the more we listen to proposals from the community and seriously consider their arguments, the greater the consensus will be. @carlitorweb as much as you advocate switching away from MediaWiki, you have to admit that there are a huge number of wikis around the world (MediaWiki, DocWiki ...), that obviously work and are also used by a sufficient number of authors. Could it not be that the cause of the poor state is to be found with Joomla and not with MediaWiki?

on point 3)
We are still far from the situation, where I am ready to agree to the variant of several separate or one single repo. Nobody has provided solid facts on this so far - only personal opinions. I cannot make a decision on this basis. However, the proposal to divide the entire documentation (help pages, user docs, dev docs and documenter docs) into 4 areas is interesting and should not be forgotten.

on point 4 + 5)
What is the purpose of the discussion about the content (pictures or not and if so, where stored) at this early stage? That is of minor importance - in general, the first thing to do is to develop a way of achieving better documentation. Design principles are forgotten here: One should separate the form of the presentation from the content (e.g. HTML/CSS) and the form should always be oriented towards the application: "Form follows Function".

on point 6)
Multilingualism in the help pages has top priority. They are the first contact of new users to Joomla. If we can only address them in English here, this is more than negative. Therefore, the desired solution must allow easy access for translators to the foreign language pages (at least for the help pages and user docs).

on point 7)
The question of how links are handled is one of the decision criteria we have to consider in point 1. A kanban board is an important tool in project management. If we can integrate it into the process with GH, it will help us to identify priorities and act accordingly. The interested contributor has nothing to do with the creation - but he can read a to-do list there and choose tasks that need to be done.

on point 8)
This point concerns all doc pages, but it is also a question that can only be solved after the decision on point 1. However, it would be important to find out the possible actions that a bot can perform. This again influences the decision for a certain system.

on point 9 + 10)
I consider the use of Git as a VCS to be indispensable. It is not for nothing that every environment in which teams work together professionally needs some kind of version control. Not least to make processes traceable and to be able to integrate different processes without collisions. Joomla's decision to use GH as a platform was made a long time ago. Whether a change to an alternative to GitLab, Bitnami etc. would be sensible or desirable - this choice is not up for discussion.

on the file structure
Here, too, it depends crucially on which system is prioritised. If we assume that the docs are divided into the areas mentioned above, each area has its own requirements for the file structure. It therefore makes no sense to focus on one of the suggestions. Such detailed specifications will arise automatically.
Cliff, I like your approach of organising the structure by topic. But the alphabetical part will no longer work as soon as translations come into play. I could imagine a prefix system like in scientific or legal essays (01-, 10.02-, 23.01.a-).

I think we all agree when I say that we want and need more contributors. So far, there is nothing in this discussion that encourages new users to sign up here.

[alann60]

It is difficult to put all your experiences aside when trying to fix and modernise.

From an outsider point of view it makes sense to get all the documents into a common format and structure. There has been discussion on flavours of Markdown but where do they differ and is there any common ground? If you look at the wiki docs there are different ways that different people have achieved in essence, the same outcomes. Is this wrong? For some reasons no, but for a project to move forwards, be sustainable and attract contributors it needs defined "how to" to documents, workflow management and oversight. Whilst some exist, they are all over the place. That is a rather simplistic statement but hopefully you can see my point.

It may be worth thinking about types of contributors to help define a workflow. Some will be fully capable of working with the Wiki. Some will be fully capable of working with a GitHub repo and some won't. Others may like sharing their experience in Joomla by writing a tutorial in a word processor. Others, like me may write guides for Joomla users in the workplace. There might be others that are happy to take a document of any type and add it to the Wiki (or whatever future system). We need a path for all types of contributor to get involved. For all this there has to be a project management system. GitHub Projects (Kanban type boards), though rather basic, provide a fairly easy to use method of visualisation and a way to empower users with a tool that encourages engagement.

Joomla support mechanisms often assume a level of understanding but that benchmark is sometimes too high. We need to have methods that assume nothing and have processes to manage as many scenarios as feasible.

Off topic but relevant - we should also remember that whilst the Wiki remains, anyone can contribute without, in my experience, any oversight or idea of what is being worked on. Should that be controlled?

[ceford]

I thought we were moving to the private repo. I have several topics to pose for information and comment.

On the last point you raised: whilst compiling lists I came across several articles offering adult services. So better control is needed.

[max123kl]

1. Alan is not yet integrated into the private repo.
2. my rejection refers to always exchanging all arguments globally at the same time in this thread, that won't work.

With that one loses the overview and if one cannot answer immediately in terms of time, it is almost impossible to discuss a certain aspect sufficiently and seriously.
If we can return to such a disciplined form of discussion, there is nothing against discussing everything publicly as well.

I therefore repeat my suggestion from this comment and suggest that we move to Issue #15. A new issue can be generated from each task in the list (at mouse-over, click on the circle on the right). This way we can deal with the topics one after the other and don't keep digressing.
Every collaborator should be able to edit the task list in the start post. This way, everyone can add their own topics and perhaps change the order. That's why I deliberately assigned only triple points to some tasks. All others can contribute with comments
As an example, I am now doing this with the current last (least important) task in order to better demonstrate my proposal.

In the end, it is also much easier to create a summary that everyone can agree on.