[Problem] Official Documentation is difficult to maintain, translate, version and reproduce

[sliptonic]

Is there an existing issue for this?

• I have searched the existing issues

Version

0.21 (Development)

Full version info

N/A.  This affects the FreeCAD ecosystem, not the software directly.

Subproject(s) affected?

No response

Problem description

The official documentation is maintained in a wiki. This system has served the community reasonably well for many years but has some severe limitations. This issue is created as a place to discuss a possible future replacement. Let's try not to jump to possible solutions yet. Instead, let's talk about the limitations of the current system, whether they can be overcome, and what an ideal solution would look like.

An ideal documentation system would have several features:

Authoring Syntax

The syntax should be as simple as possible and allow good readability for the source. This makes it easier for casual contributions from non-experts. If the syntax is too complicated, fewer people will contribute. Markdown is very good here.

Authoring tools

Casual contributors should be able to make quick changes directly from the web. Advanced users should be able to work with a local editor.

Git version control.

The workflow around documentation should use the same tools and processes that we use for the software itself - Issues, pull requests, "code review", etc.

Translation

The system should interface well with Crowdin or similar translation platforms.

Software/Document Versioning

We should be able to keep documentation online for previous versions of the software.

Formats

It should be possible to generate an offline copy like an Epub for reading on a kindle or other reader.

Integration with the software.

The documentation should feel like part of the user experience, not a separate thing.
Should we be able to create stub pages directly from the source code?

Import Capability

It should be possible to automatically import our current data

Export Capability

It shouldn't create lock-in that prevents us from moving to a different system in the future.

Anything else?

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[chennes]

It's probably part of the "translation" solution, but one of the major drawbacks of the current wiki system is that searches aren't confined to a single language, so your search results almost invariably return ten different copies of the same page, in all different languages. I think that any system we decide to migrate to should have a more clearly-defined separation when searching, so you only get your chosen language in the results (or I suppose the base page if no translation exists yet?).

[obelisk79]

Another consideration for WIKI management should include research into adding a functional WYSIWYG editor. Creating a page using syntax formatting and having to preview to see the end result can get tedious during major edits. I believe there are a few existing plugins which work with our wiki system.

Another thought, is that for any software feature change/addition/removal, someone should volunteer to make wiki updates before such a PR gets merged to minimize deprecation of information.

Would it be possible to setup the wiki to function similarly to a forum with content moderation?
Explanation of what I mean:
-Wiki is opened up for anyone to freely create an account and submit edits.
-A group of wiki accounts are established separate from Administrators to function as moderators to review edits and approve them as a means to filter out inappropriate spam or poorly created/formatted content.

Lastly, +1 on Chris's comment about search results not being limited to one language translation. I'm not finding an apparent solution to this using MediaWiki. However being the same platform wikipedia is built on, I can't imagine that this would be impossible.

[luzpaz]

Related:

• As chennes mentioned above Omitting translation pages in Wiki search results FreeCAD-Homepage#96
• Add links to this github repo from the website (so users can improve) FreeCAD-Homepage#34 (ideally we can have this for documentation as well)

[silopolis]

Le ven. 18 nov. 2022 à 15:54, sliptonic ***@***.***> a écrit :

Authoring Syntax The syntax should be as simple as possible and allow good readability for the source. This makes it easier for casual contributions from non-experts. If the syntax is too complicated, fewer people will contribute. Markdown is very good here.

AsciiDoc is really nice to use too. reStructuredText may be archer, but ain't nothing like it semantically (but special MD syntaxes like MyST may be worth investigating...) Authoring tools

Casual contributors should be able to make quick changes directly from the web. Advanced users should be able to work with a local editor.

That web editing requirement is where most of the text based, git manageable solutions get pushed out of the game :'( AFAIC, strength of rst/md/adoc based documentation systems largely compensate the loss of web editing capability, all the more as all major IDEs offer good preview features Translation

The system should interface well with Crowdin or similar translation platforms.

Crowdin directly supports Markdown and AsciiDoc, potentially avoiding the intermediate gettextization and later generation of translated sources before building the docs. Nevertheless, it is questionable whether it is a wise choice versus a standard Gettext based pipeline using po4a or sphinx-intl for example. This is surely a more involved setup, but would make the pipeline compatible with almost all translation tools available, from PoEdit on the Desktop to any of the Web platforms, Crowdin of course, but Weblate, Transifex... you name it. If chosen, generating a translation resource (PO file) per doc page makes translator's life a bit sweeter than a massive single resource, as it preserve more strings context. Internationalization support in Antora, Sphinx counterpart in AsciiDoc land, isn't builtin yet AFAIK. Software/Document Versioning

We should be able to keep documentation online for previous versions of the software.

This is indeed a must but more or less handled by the various documentation generators. Import Capability

It should be possible to automatically import our current data

Yorick once worked at converting the Wiki to Md as I understand it: https://github.com/yorikvanhavre/FreeCAD-documentation

Export Capability It shouldn't create lock-in that prevents us from moving to a different system in the future.

Pandoc support of the chosen format and gettext use would make lock-in almost difficult ! Anything else? Somehow being a Python shop, using Sphinx or MkDocs may be beneficial for a nice and intimate integration with API documentation, which could be specially valuable for the dev docs.

[chennes]

Does anyone have experience with Docusaurus? https://github.com/facebook/docusaurus

It's open source, MIT licensed, and seems to check all of our boxes. There are some scripts out there to help migrate mediawiki into it.