#797 - [Howto] - Decide on future CMS for howto.disroot.org - Disroot/Disroot-Project - Disroot Forgejo: Brace yourself, merge conflicts ahead.

muppeth commented

2024-02-21 18:20:56 +01:00

Owner

This discussion is to decide whether we move our tutorials from https://howto.disroot.org from current GRAV to different CMS. We will discuss all pros and cons for each scenario and possible software solutions. The outcome of this decision will determine the next steps.

Criteria are following:

Easy to submit or update tutorials for everyone
Easy to submit, update and maintain translations

Once decided check #783

This discussion is to decide whether we move our tutorials from https://howto.disroot.org from current GRAV to different CMS. We will discuss all pros and cons for each scenario and possible software solutions. The outcome of this decision will determine the next steps. Criteria are following: - Easy to submit or update tutorials for everyone - Easy to submit, update and maintain translations Once decided check https://git.disroot.org/Disroot/Disroot-Project/issues/783

muppeth added the

Discussion

Howto

labels 2024-02-21 18:20:56 +01:00

muppeth referenced this issue

2024-02-21 18:23:50 +01:00

[2024 Project goals] - Improve howto website #783

fede commented

2024-02-22 05:13:49 +01:00

Owner

I was looking for either a better use of Grav or a better solution on how to manage our documentation taking into account ease of use, resources required, easy to manage participation and user experience when collaborating (trying to avoid the use of Git). Below is a list of the software I have been reviewing/testing.

Software name -> Markdown support -> Database -> WYSIWYG editor
MkDocs (http://www.mkdocs.org/) -> Markdown -> No database -> No editor
Wiki.js (https://js.wiki/) -> Markdown -> Database -> WYSIWYG
BookStack (https://www.bookstackapp.com/) -> Markdown -> Database -> WYSIWYG
VitePress (https://vitepress.dev/) -> Markdown -> No database -> No editor
Vrite (https://vrite.io/) -> Not specified -> No database -> WYSIWYG
NextBook (https://next-book.vercel.app/) -> Markdown -> No database -> No editor
ReadTheDocs (https://readthedocs.org/) -> Markdown -> No database -> No editor
Sphinx (http://www.sphinx-doc.org/) -> reStructuredText (Md via plugin) -> No database -> No editor
docz (https://www.docz.site/) -> MDX -> No database -> No editor
Daux.io (https://dauxio.github.io/) -> Markdown -> No database -> No editor

Of all of them, personally, I think BookStack is the best and most original solution. The user and documentation management is very good, the WYSIWYG editor is super simple to use and very complete, it doesn't need Git, it can be customized, it has a very friendly interface, light and dark themes, and a very intuitive document organization. It also support language switching.

The rest of them work, more or less, the same way, except for Vrite, which is really nice too but it still under heavy development (alpha).

Regarding translations, I've been checking the following self hosted software:

Last two are not completely free/open source software. Weblate seems the better option although all of them are very complete and easy to use.

I was looking for either a better use of Grav or a better solution on how to manage our documentation taking into account ease of use, resources required, easy to manage participation and user experience when collaborating (trying to avoid the use of Git). Below is a list of the software I have been reviewing/testing. - Software name -> Markdown support -> Database -> WYSIWYG editor - MkDocs (http://www.mkdocs.org/) -> Markdown -> No database -> No editor - Wiki.js (https://js.wiki/) -> Markdown -> Database -> WYSIWYG - BookStack (https://www.bookstackapp.com/) -> Markdown -> Database -> WYSIWYG - VitePress (https://vitepress.dev/) -> Markdown -> No database -> No editor - Vrite (https://vrite.io/) -> Not specified -> No database -> WYSIWYG - NextBook (https://next-book.vercel.app/) -> Markdown -> No database -> No editor - ReadTheDocs (https://readthedocs.org/) -> Markdown -> No database -> No editor - Sphinx (http://www.sphinx-doc.org/) -> reStructuredText (Md via plugin) -> No database -> No editor - docz (https://www.docz.site/) -> MDX -> No database -> No editor - Daux.io (https://dauxio.github.io/) -> Markdown -> No database -> No editor Of all of them, personally, I think BookStack is the best and most original solution. The user and documentation management is very good, the WYSIWYG editor is super simple to use and very complete, it doesn't need Git, it can be customized, it has a very friendly interface, light and dark themes, and a very intuitive document organization. It also support language switching. The rest of them work, more or less, the same way, except for Vrite, which is really nice too but it still under heavy development (alpha). Regarding translations, I've been checking the following self hosted software: - Weblate (https://weblate.org/) - Traduora (https://traduora.co/) - Tolgi (https://tolgee.io/) - Lokalize (https://lokalise.com/) - Transifex (https://www.transifex.com/) Last two are not completely free/open source software. Weblate seems the better option although all of them are very complete and easy to use.

muppeth added

Goal 2024

and removed

Discussion

labels 2024-03-03 11:13:19 +01:00

muppeth added this to the 2024 Goal - Improve howto website project 2024-03-03 11:13:34 +01:00

muppeth changed title from ~~[Decission] - Change CMS or stay with GRAV~~ to [Howto] - Decide on future CMS for howto.disroot.org

2024-03-03 11:15:18 +01:00

fede added this to the 24.03 - March milestone 2024-03-03 17:03:48 +01:00

fede self-assigned this 2024-03-03 17:14:24 +01:00

meaz commented

2024-03-09 12:10:52 +01:00

Owner

Nice work @fede

Can weblate be used easily with BookStack for example? How?

Nice work @fede Can weblate be used easily with BookStack for example? How?

fede commented

2024-03-17 16:44:32 +01:00

Owner

As far as I could check, no, it doesn't.

The thing is that BookStack doesn't use Git but its own database. This makes things a lot easier for "non-tech" people or to avoid Git. But it's a big issue when it comes to translations solutions since most of them requires Git in the back to allow a better, effective workflow.

So, options would be (so far):

use a documentation software with Git integration (like most of the solutions without WYSIWYG editor); or
use a documentation software with WYSIWYG editor and its own built-in translation options (Wiki.js, for example).

As far as I could check, no, it doesn't. The thing is that BookStack doesn't use Git but its own database. This makes things a lot easier for "non-tech" people or to avoid Git. But it's a big issue when it comes to translations solutions since most of them requires Git in the back to allow a better, effective workflow. So, options would be (so far): 1. use a documentation software with Git integration (like most of the solutions without WYSIWYG editor); or 2. use a documentation software with WYSIWYG editor and its own built-in translation options (Wiki.js, for example).

meaz commented

2024-03-23 10:14:22 +01:00

Owner

I don't see the difference between how Wiki.js and Grav handle other languages. If I get it right, in both case, you need to have a file for each language. See https://docs.requarks.io/locales

fede commented

2024-03-23 14:30:11 +01:00

Owner

All of the solutions available requires to have a file per language. In that regard, there's no difference between any of them. The difference is how these solutions deal with the translation process. Some of them via Git, others via a built-in editor.

muppeth commented

2024-03-31 08:14:08 +02:00

Author

Owner

First of, @fede hat's off for all the work. Secondly sorry for wall of text.
I did check the list and looked additionally for "knowledge base" software solutions trying to find something that would fit our needs, but indeed there isn't much choice. Every solution was lacking in one way or another in key features we set as a goal. Mainly the lack of proper automated translation integration with services like weblate or alike. Since this is not the case in either, we will need to bake our own solution to it. The question then remains about two factors: built-in text editor, theme/structure.
Built-in editor allows others, less techy folks to participate in writing and tutorials or translations. However, we might loose the ability control the changes if those are saved directly on the website and do not go through git. Especially in situation where if we were to use in some way translation software, this might become messy.

Theme wise, I do think software solution built for the use-case as ours would be more suitable, but I also think it should not be JS dependent. This leaves us with just handful options. Wiki like stuff I personally aren't big fan of. BookStack seems to be interesting, but I don't know how it handles the files. I think it uses database for content which would IMO eliminate it from the race. Sphinx, does not use markdown directly but does handle data in the same way we currently use (git).

Sphinx seems like atm the best candidate if we look at new solution, but I wonder if this is enough to decide to totally change current webiste. If we still going to use git for version control and still need to find our own way to do and maintain translations, I wonder if this warrants the change.

Perhaps instead we should focus on the current setup and improve it in the areas where it lacks. I would propose to (in order of execution):

Stay on Grav since no other solution significantly improves quality of life here.
Develop new theme that will make it easier for users to navigate through our little jungle and at the same time will look good.
Change file structure and organization so that all sections of the repository follow the logic needed for the theme.
Review and cleanup all existing tutorials. Make them more unified, simple to understand and to the point. Perhaps create text in such a way where things like domain name, sevice url, project name could be turned into variables. It would allow future projects or disroot nodes to easily pull and adjust the repo for their implementation (we should make sure to use appropriate license to not get screw over by for profits)
Use chatgpt (or other) to create initial translations for all languages we want to support. I think current language models are quite competent (even those you could use on your own machine) and could deliver on good translation. In this way we would not have "holes" in translation (where some tutorials arent translated and others are). Once we have the initial version of translations, users could improve them but would not have to write them from scratch.
(optional) Deploy weblate and think of a workflow to keep track of translations and changes, to update the weblate and then pull the updates back into the texts on the site repo. This will require additional work from someone who's role would be to control that aspect (depending on how much we can automate stuff). First we should see if the "AI" translations are good enough and whether this is at all necessary. If AI does a decent job, I wonder if the entire operation of using weblate and having a dedicated person working on it is justified.

First of, @fede hat's off for all the work. Secondly sorry for wall of text. I did check the list and looked additionally for "knowledge base" software solutions trying to find something that would fit our needs, but indeed there isn't much choice. Every solution was lacking in one way or another in key features we set as a goal. Mainly the lack of proper automated translation integration with services like weblate or alike. Since this is not the case in either, we will need to bake our own solution to it. The question then remains about two factors: built-in text editor, theme/structure. Built-in editor allows others, less techy folks to participate in writing and tutorials or translations. However, we might loose the ability control the changes if those are saved directly on the website and do not go through git. Especially in situation where if we were to use in some way translation software, this might become messy. Theme wise, I do think software solution built for the use-case as ours would be more suitable, but I also think it should not be JS dependent. This leaves us with just handful options. Wiki like stuff I personally aren't big fan of. BookStack seems to be interesting, but I don't know how it handles the files. I think it uses database for content which would IMO eliminate it from the race. Sphinx, does not use markdown directly but does handle data in the same way we currently use (git). Sphinx seems like atm the best candidate if we look at new solution, but I wonder if this is enough to decide to totally change current webiste. If we still going to use git for version control and still need to find our own way to do and maintain translations, I wonder if this warrants the change. Perhaps instead we should focus on the current setup and improve it in the areas where it lacks. I would propose to (in order of execution): 1. Stay on Grav since no other solution significantly improves quality of life here. 2. Develop new theme that will make it easier for users to navigate through our little jungle and at the same time will look good. 3. Change file structure and organization so that all sections of the repository follow the logic needed for the theme. 4. Review and cleanup all existing tutorials. Make them more unified, simple to understand and to the point. Perhaps create text in such a way where things like `domain name`, `sevice url`, `project name` could be turned into variables. It would allow future projects or disroot nodes to easily pull and adjust the repo for their implementation (we should make sure to use appropriate license to not get screw over by for profits) 4. Use chatgpt (or other) to create initial translations for all languages we want to support. I think current language models are quite competent (even those you could use on your own machine) and could deliver on good translation. In this way we would not have "holes" in translation (where some tutorials arent translated and others are). Once we have the initial version of translations, users could improve them but would not have to write them from scratch. 5. (optional) Deploy weblate and think of a workflow to keep track of translations and changes, to update the weblate and then pull the updates back into the texts on the site repo. This will require additional work from someone who's role would be to control that aspect (depending on how much we can automate stuff). First we should see if the "AI" translations are good enough and whether this is at all necessary. If AI does a decent job, I wonder if the entire operation of using weblate and having a dedicated person working on it is justified.

👍 3

meaz commented

2024-04-06 07:47:56 +02:00

Owner

I would also add to perhaps try not to have html or css in the .md files, if that is possible. That would make things easier for translators.

meaz referenced this issue

2024-04-06 08:04:57 +02:00

[New site] - Decide how to handle translations #844

muppeth closed this issue

2024-04-10 21:11:35 +02:00

[Howto] - Decide on future CMS for howto.disroot.org #797