[Problem] Official Documentation is difficult to maintain, translate, version and reproduce #10203
Replies: 6 comments
-
|
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?). |
Beta Was this translation helpful? Give feedback.
-
|
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? 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. |
Beta Was this translation helpful? Give feedback.
-
|
Related:
|
Beta Was this translation helpful? Give feedback.
-
|
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.
|
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
Have there been any changes to the documentation recently? After the home screen, every page I've tried is a 502 error. |
Beta Was this translation helpful? Give feedback.
-
Is there an existing issue for this?
Version
0.21 (Development)
Full version info
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
Beta Was this translation helpful? Give feedback.
All reactions