Hi Richard,

I feel so happy being part of this community when I read e-mails like these.

Thanks a lot for your strong words, especially since we discussed an earlier version of this exact document [1] during the SUSE Hack week on Monday 22 March and based on that document you made some changes to MicroOS (mainly in the first boot script) which have been reflected in the document after. Also because of that discussion I've added a few extra comments on the highlighted comments:

!!! info Full disk encryption is not recommended for SSD's as trimming is currently not supported due to the read only nature of the / filesystem during boot.

!!! info It is NOT recommended to install snaps on openSUSE MicroOS, there is a possibility this will break during an update or reboot


Also as you can see in the earlier version (isn´t it nice that we can go back in time now..). Both the snaps and virtualbox were included in that version, and we even discussed them, where you stated (as you always do) that snaps are not safe and you will not support VirtualBox.

Also on a personal note, this document started as a manual for me personally [3]  for what I do when I reinstall MicroOS and wanted to share it with the world, if anyone asks me something about MicroOS I point them to this new version. Which btw has been shared numerous times in the Discord/Telegram/Matrix group from openSUSE.

best,
Syds

[1] https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/78f6e2b9e08792d035f7a97d5229305915a57201/project/docs/microos_getting_started.md

[2] https://en.opensuse.org/MicroOS/Downloads/Leap

[3] https://syds-git.github.io/

[4] https://events.opensuse.org/conferences/oSAS21/program/proposals/3635

On Sun, Aug 8, 2021, at 14:23, Richard Brown wrote:


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:

https://opensuse.github.io/openSUSE-docs-revamped-temp/microos_getting_started/

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?
Unofficial does not mean nobody uses it
- there has never been an official/non-experimental Leap version of MicroOS
Yes there has been a version of Leap, you can find it on [2]. We wanted to make sure that we point out that Leap is not in  scope.
- GNOME MicroOS is beta and ok for testing, KDE is alpha and totally not suitable for anyone IMO. This is not documented. Why?
Because sometimes people want to use it. Not everybody uses Gnome. If we give the option to install it, why not give the extra steps necessary to actually start using it.
- AFAiK no one in the MicroOS team will ever support the use of snaps on MicroOS, ever. Why does this document imply otherwise?
Cause I wanted to find out if they work. Also there was a presentation about MicroOS and snaps on the openSUSE Asia Summit today.. {4]
- the document repeatedly suggests the bad practice of using transactional-update shell unnecessarily. Why?
It does not suggest using the shell. It shows that somethings that are not possible during a normal boot and gives the actual option to do it.

The usage of the shell is the entire reason i prefer and love MicroOS.
- the snapd documentation includes instructions for installing known-insecure, failed-a-SUSE-audit software on users machines. How is this quality control?

Based on our conversation on the 22nd of March I added your comment that it is NOT recommended to install snaps. Your comment about the quality control is something you care about more than people that use snaps. I'm not saying you should install them. I'm saying if you want to install them, this is how it works.

The manual from snapcraft is incomplete and does not work on MicroOS.
- as MicroOS release manager I do not support virtualbox on MicroOS - why is this documented?
Cause I use it. You do not need to support something you don´t use. It's already supported on Tumbleweed which is the base of MicrOOS.


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.
Wrong in your eyes does not mean it is wrong for other people. You know everything from this guide already. Some new people however do NOT.

-1 from me.