On 8. Aug 2021, at 14:11, Attila Pinter <adathor@protonmail.com> wrote:
‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐On Sunday, August 8th, 2021 at 6:52 PM, Carlos E. R. <robin.listas@telefonica.net> wrote:On 08/08/2021 13.29, jdd@dodin.org wrote:
Le 08/08/2021 à 13:24, Carlos E. R. a écrit :
The closer I can get is LyX, which is related to latex, also a markup
editor.
but still much better for prints than for web :-)
True.
But it is a question of preparing a correct set of templates and
procedure to generate the desired output.
the present mediawiki implementation (the one of openSUSE wiki, if I'm
right) is the most well known, thanks to Wikipedia, so a good choice,
even if not the best tool
Yes.
The Wikipedia is possibly the most successful documentation community
effort ever, and our wiki uses basically the same system. Of course it
has problems, but making access and writer contribution harder I don't
think is the solution.
Not sure if you mean that the revamped docs is the project that makes contribution or access harder. If yes than I have to say that it is very much not the case. Before we settled on the current solution - which is MKDocs - we checked out about 12 different solutions. The reason we picked this one is because it has the lowest barrier of entry. Markdown is easy, a lot faster can be learnt than an ancient LaTeX style language and contributions can be proof read before merged into the main docs and made public making sure that there is nothing weird or false goes in to it causing issues for users.A great example as to why this project even exists is the checksum help (https://en.opensuse.org/SDB:Download_help#Checksums) page that is linked under every openSUSE distro's download page on get-o-o. That was so outdated that it didn't even offer a valid solution for users to correctly check their TW/MicroOS/Kubic iso after downloaded. We went out, looked up the correct procedure and updated the page to reflect the correct information. Same thing happened during the release of Leap 15.3. Nobody was changing that page although it is incredibly important.Bottom line is that for a serious project to have a Wiki style doc labeled as official doc can't be a reasonable expectation. Anybody can edit or write whatever they feel like true or not. But, with that being said, the intention is not to demolish en-o-o, but to provide a single source of truth to reoccurring issues, installation manuals, etc. that users face. The goal is to prevent users from opening 3+ years old unmaintained docs and expect that it is checked, reviewed, and tested, and works for their situation.Br,
Regardless of the homework you’ve done, the fact remains - it’s harder to update your new docs than the old wiki.
This is done in the name of quality control, but let’s have a look at a document you have posted there on a topic I have intimate knowledge about:
Inaccuracies/Omissions:
- there is no mention of the actual intended/supported use of MicroOS - the Desktop use of MicroOS is experimental - why does our new wannabe “official” documentation cover unofficial experiments?
- there has never been an official/non-experimental Leap version of MicroOS
- GNOME MicroOS is beta and ok for testing, KDE is alpha and totally not suitable for anyone IMO. This is not documented. Why?
- AFAiK no one in the MicroOS team will ever support the use of snaps on MicroOS, ever. Why does this document imply otherwise?
- the document repeatedly suggests the bad practice of using transactional-update shell unnecessarily. Why?
- the snapd documentation includes instructions for installing known-insecure, failed-a-SUSE-audit software on users machines. How is this quality control?
- as MicroOS release manager I do not support virtualbox on MicroOS - why is this documented?
In short - this guide is horrifically wrong, and does nothing to suggest that the revamped docs will be anything less than an even messier wiki, just one thst will take longer and more effort to correct when people post junk to it.
-1 from me.