Using this repo

[ceford]

I think that using this repo is fine whilst we are experimenting with procedures. When we have established that we know what we are doing we might think about a more formal Joomla owned repo.

[alann60]

Yes I think this is testing ground

[alann60]

For my understanding, a lot of the conversation has been around PRs and the developer docs.

Are we talking only about the MediaWiki or are you actively getting involved with the developer docs platform too?

I'm not familiar with the PR side of things but if I can see where I can help through this repo (or ultimately the Joomla one) it will be a big step forward.

@ceford the document referred to in Issue#2 that is super useful for documenters and I know you have provided numerous links over time in both Glip and Mattermost as has @max123kl.

Having a curated list of all these links would be a great benefit moving forwards. Also, in the Issue #2 document, there are some tags I have never come across before and an all in one place reference would also be great asset.

[max123kl]

Here on GH, the markup language is Markdown. There is a Cheat Sheet and other helpful pages.
The CONTRIBUTING.md tells you a simple step-by-step description.

Writing a FAQ here in the Wiki may be a good point to help those who are new to Git/GitHub.
So if a question occurs, write it down there. I'll try my best to answer it.

If you want to bring in a new commit, follow the contributing file and ask if something is not well explained.

[ceford]

@alann60

Are we talking only about the MediaWiki or are you actively getting involved with the developer docs platform too?

In my opinion, the decision to move Developer docs to Docusaurus is misguided. My big gripe is the lack of translation - it has been decided the Developer docs will be in English only. It is progressing at a snails pace and very few people are contributing. We could separate the Docusaurus part from the GitHub part. If the content is in GitHub we could use mdBook for delivery instead of Docusaurus. But as I have pointed out elsewhere we may as well use Joomla.

So what about moving Help screens and User Tutorials to GitHub? No obvious easy translation method! Complicated approval and contribution merging! So no thanks! I have looked at Crowdin - it seems to break text into individual sentences. Right now I think I/we focus on MediaWiki and User Documentation.

[carlitorweb]

@ceford The main goal of all this, is try get new contributions from developers/aministrators/users. Do you think mediawiki is suitable for that? Even us, who try do it, sometimes is frustrating.
The fact is that with the passage of time fewer and fewer are contributing, mainly because they get stuck with the mediawiki platform. I think we cant deny this fact.

My main interest in trying to move the documentation is because of this fact. It's not that I want to use github or other platforms, it's that we have to find/try another alternative that allows us to make these contributions.

You want use Joomla? Let do it. This mean a custom implementation, and mean a lot of work, but in the long run it will benefit everyone. We can use only the Joomla Framework and do some type of job similar to the issue.joomla.org.
Or we can use the CMS, and do the implementation there.

My point again, what we need is new contributions, the way of get it can be any, since any solution we find suitable for us, will be enough for accomplish this goal.

[alann60]

@ceford I share your opinion on Docusaurus and think there should be a single platform. From the start of me getting involved the fact that docs wasn't a Joomla site made no sense to me until it was explained to me about the translations, spam etc. A single platform provides flexibility for writers to handle material they "signed up" for but perhaps also to be able to assist with a document they don't have to fully understand but are able to add to the "document system". Currently, I have no time to write for both developer and user docs as there is such a lot to do on the user docs. But, in an ideal world moving forwards, who knows?

I also agree with sticking with the MediaWiki while someone comes up with a better alternative. It has it's problems but is that something that could be fixed if someone could be found to do it? The biggest issue I see for bringing contributors on board is the JDocs structure / organisation and sufficient resources as reference points in a single place. A repo like this would, I feel help.

That said, given what you have achieved with the User Manual in Joomla, it offers a viable compromise and a way to have a better structured, and functional document site.

[ceford]

As I see it we have three Manuals to convert from Mediwiki format to GitHub format:

1. Help pages
2. User Tutorials
3. Developer Tutorials

There are about 200 Help pages and about 300 useful User Tutorials, and all of their translations. I know how to automate the conversion and propose to spend a couple of days working on that. So at the moment I am more interested in what we have already rather than upcoming changes.

I am going to create a new repo and I am pondering the structure. I have already subdivided tutorials into related sections. These are my lists:

https://docs.joomla.org/J4.x:Joomla_4_Help_Screens
https://docs.joomla.org/J4.x:Joomla_4_User_Manual_Index
https://docs.joomla.org/J4.x:Joomla_4_Developer_Manual

Right now I am unsure whether it is best to use separate repos for each project or put them all in one repo. The structure would be something like this:

repo/
repo/user-manual/
repo/user-manual/en(-GB?)/
repo/user-manual/en(-GB?)/getting-started/
repo/user-manual/en(-GB?)/getting-started/introduction.md
repo/user-manual/en(-GB?)/getting-started/core-features.md
...
repo/user-manual/en(-GB?)/articles/core-features.md
...
repo/user-manual/de(-DE?)/

For the moment I propose to leave images on the MediaWiki server as that is what I do with JDOC Manual.

[carlitorweb]

Hackwar made an good suggestion, and since we are starting to get all of us in the same page, our implementation should be similar to that.

I will add also translations should be done using crowdin. They have even a GitHub action who can help in this matter.

https://github.com/crowdin/github-action

In my opinion, we should separate the help screen and give his own repo. The CMS for get the help screens from this repository will be very easy. Even a GitHub Pages can be done if is needed.

[max123kl]

using crowdin

I'm not very familiar with Crowdin - but I don't like it so far

we should separate the help screen and give his own repo

We can have a separate folder for this - a separate repo needs to be watched. So this means a higher effort.

[carlitorweb]

We can have a separate folder for this - a separate repo needs to be watched. So this means a higher effort.

My though was more for serve this independent repository for the Help buttons within the CMS. But maybe you have right, 2 repo will be to much for ask to the organization

[max123kl]

The help pages are part of the Jdocs wiki with their own namespace. When you click the help button within a Joomla session, the page is called via a proxy from the wiki.
I agree with the idea from cliff to have a separate folder for the help pages. A separate repo is not needed.

[max123kl]

For the moment I propose to leave images on the MediaWiki

I agree, new images should be able to upload (via PR) here as well (see these are needed to update a wiki template)

[ceford]

Another light bulb moment: why are we using GitHub? It comes with its own complications that can be avoided if we do everything in Joomla. Outline: we store gfm (markdown) in the database and edit that with simpleMDE. Save and also save an md to html conversion for delivery; translation: side by side English and Non-English edit forms. Versions: save to local git repo? Push to GitHub?

Another project to keep me amused for a few days! Could be an extension for any general purpose documentation.

[carlitorweb]

GitHub is only where we should storage the markdown files with a proper structure.

From there, we can use any interface for edit those files. Can be directly on GitHub with a PR. Can be a Joomla interface who make the push after a file is edited using this interface...

[max123kl]

That's the idea I prefer too

[ceford]

If you are converting mediawiki to github markdown for Docusaurus the file needs this at the top:

___
sidebar_position: 500
id: {$id}
title: {$title}
___

where {id} is the mediawiki file name without the namespace (e.g. J4.x:) and with _ replaced with -.
{title} is the title without the terminating language string (e.g. /en)

Example:

// create a header - may need to be changed later
// ---
// sidebar_position: 1
// id: getting-started-with-joomla
// title: Getting Started with Joomla
// ---

In MediaWiki the users are allowed to translate the title. That makes correlation in Docusaurus difficult. Not to mention translation. Which is what prompted me to ask Why use GitHub.

[max123kl]

Why use GitHub.

Main reason Because of the version controlling features

We are all quite new to this workflow, and it will happen to make something wrong.
Reverting to a former state is essential!

[carlitorweb]

converting mediawiki to github markdown for Docusaurus

I not saying we are going to use Docusaurus. Jus want point out, when you use a global syntax like markdown for store the content, you have lot of options after to see what tools fit better to us for view/manage this content

[alann60]

As a Joomla site builder and user, I have contributed some tutorials, made some amendments and built up the J4 Portal page as requested by Mike Brandner.

I will help with anything I can with a few hours a week, more when I can.

I'm getting a little lost though with some of the discussions. I'm not a developer so some of the discussion is lost on me. We should also assume that not all contributors will be developers, nor need to be to produce documents.

Looking from the outside in and from my perspective I see the purpose of this repo to:

• Discuss current issues with the existing document base
• To separate and structure Help Pages, User Documents and Developer Documents
• To convert and store said documents in Github flavour Markdown making them multi purpose "starters" for moving between documentation platforms if and when that were to happen
• To provide guidance and support for document writers
• To establish a workflow process that a document writer can utilise
• To control document creation by providing and managing a list of requirements and a method for a writer to either self assign or be assigned tasks
• To simplify document creation
• To receive, review and allocate PRs to the workflow process
• To provide a way for material to be received for a writer to use as or in a user/developer document

If I was just starting out as a new contributor, some sort of onboarding would be beneficial and I would like to be able to see how I can help, the type of work required, do's and don'ts, guidelines and templates / snippets - available all in one place or linked from one place.

I want to check that this is where we are heading?

[max123kl]

I am currently preparing a text that I will put on the Repo Wiki. It will contain a few basic tips and also how possible errors can be fixed. I hope that newcomers will then find it easier to get started with the process of GH, issues and PRs. I am also not a developer and do not know how to program. The way of working is very easy to structure logically. If we follow this workflow in an exemplary manner, then participation is really not difficult. If we can then attract some new authors, it will really be an exciting and successful thing.

[ceford]

@alann60 Good summary

@max123kl I have a documenters manual but I had not intended to upload its contents because it is all MediWiki related and I am looking ahead. However, it would seem to make sense to include it alongside the other manuals: help, user, developer and now documenter.

[max123kl]

In my post, I spoke about the GH workflow only
@ceford that makes sense anyway - maybe with some minor adjustments for each