Hey Axel,

How should this be done? Adding a box like

<syntaxhighlight > Please note that this page will be soon migrated to https://opensuse.github.io/openSUSE-docs-revamped-temp/index.html </syntaxhighlight>

at top of the page?

This can serve as good starting template, yup! As long as people helping report thoroughly their interventions to us, we can come and clean behind to ensure a consistent wording. And that's phase 1 of the plan. Phase 2 is: phasing out the pages with a proper reference as described in my original post.

...

3) report to us and help us migrate gracefully (i.e. check the contents, format them, merge them, and finally replace them on the relevant wiki pages with a single link pointing to their new location)

'Report to us' does probably not mean that you want to get bombed by EMails. Is there a page or something where the wiki pages are added?

In last January I started this: https://etherpad.opensuse.org/p/wiki-pages-reporting. It was not entirely satisfying. From this I have learnt two things: - reduce scope (it lacked a clear scope because it applies to virtually all the wiki) - don't allow for hit-and-run tactics (people just ticking a box and leaving out of sight) What fixes the first mistake: Now I want something simpler, with a smaller scope: you look at our Table of Contents, you look for things that strongly overlap with it, and you flag them as described. What fixes the second mistake: - flagging pages implies a commitment to help us migrate them - migrating a pages implies some talking about formatting, wording, submitting, merging - therefore, flagging pages implies some talking Conclusion: - yes, please spam us - if you spam us we can divide the work so that everyone has little work and everything is covered.

Thanks for this initiative! Axel

Dne středa 4. srpna 2021 16:37:49 CEST, Adrien Glauser napsal(a):

...

I think this is very good idea. I have few questions: 1) What is/will be relationship to https://doc.opensuse.org/?

Perhaps, I haven't heard anything from the folks in charge of it. From the user's perspective it would be good to have everything hosted there. What we are doing is a "practical user guide centered on usability and recommendations", so it does not stop at the pure technical facts and sometimes discusses topics and puts them in perspective.

From readers' perspective I think single place for documentation would be the best. Otherwise there will always be confusion similar to wiki vs. doc.

...

2) Will there be any possibility to translate the content?

Yes, weblate.

Perfect :-) -- Vojtěch Zeisek https://trapa.cz/ Komunita openSUSE GNU/Linuxu Community of the openSUSE GNU/Linux https://www.opensuse.org/

Gerald Pfeifer wrote:

(Sorry, I probably missed something, so figured I'd better ask.)

I feel like I've also missed something - is the wiki being depreciated/decommissioned ? Will contributing be as easy as it used to be? -- Per Jessen, Zürich (19.1°C) Member, openSUSE Heroes

Now: - doc.opensuse.org: Leap manuals, containing list of features, commands, instructions for operating these commands to use the features, and a few contextual information, centered on Leap workflow; - wikis: Leap + Tumbleweed user guides not safe to use because featuring a mix of up-to-date, best-practice info with outdated or not best-practice infos - new docs: designed to gradually replace all parts of the wikis which strongly overlap what there is already on our table of contents, wedding technical details, instructions, and best-practice, accomodating in particular TW workflow and all the tools commong to TW and Leap (which has a much simpler workflow) After the migration: - doc.opensuse.org: Leap manuals & new docs - wiki, without the contents falling in the scope of Leap manuals or the new docs (which means some deprecated or unsafe contents for Leap, which the folks from doc.opensuse.org may want to sanitize, but that's outside of the scope of this topic)

I have given a list of necessary and sufficient conditions for what counts as "relevant" in my first post, and answered exegetical questions after that. By now you have more than enough context to figure out whether a page you'd care to see in the new docs should be flagged or not. If you are still unsure, do just flag it. It won't be difficult to filter out false positives in due time. Thanks in advance for your help! Le 05/08/2021 à 11:02, Per Jessen a écrit :

Adrien Glauser wrote:

...

Now: - doc.opensuse.org: Leap manuals, containing list of features, commands, instructions for operating these commands to use the features, and a few contextual information, centered on Leap workflow; - wikis: Leap + Tumbleweed user guides not safe to use because featuring a mix of up-to-date, best-practice info with outdated or not best-practice infos - new docs: designed to gradually replace all parts of the wikis which strongly overlap what there is already on our table of contents, wedding technical details, instructions, and best-practice, accomodating in particular TW workflow and all the tools commong to TW and Leap (which has a much simpler workflow)

After the migration: - doc.opensuse.org: Leap manuals & new docs - wiki, without the contents falling in the scope of Leap manuals or the new docs (which means some deprecated or unsafe contents for Leap, which the folks from doc.opensuse.org may want to sanitize, but that's outside of the scope of this topic)

Wait - I thought you said "contents that apply to Tumbleweed" will be moved to "the new docs" ? I think I have a wiki page somewhere, where I describe how I use 1-wire sensors with an ARM board - I most probably wrote it with Leap in minds, but it would apply equally well to Tumbleweed.

Where will that go in the new setup, and if it moves out of the wiki, how would I update it?

I have spent many keystrokes trying to address all your questions. I have no reason to believe that I will be able to improve on my earlier attempts. We'll need to rely on other participants who might have got what I've tried to say and will be able to make up for my own lack of explanatory skills. How to update migrated contents? Just like you update code: by lodging PRs. As far as I am concerned I have always tried to be receptive to people unfamiliar with git, by accepting Markdown-formatted files and registering a PR for them. Le 05/08/2021 à 20:51, Per Jessen a écrit :

Adrien Glauser wrote:

...

I have given a list of necessary and sufficient conditions for what counts as "relevant" in my first post, and answered exegetical questions after that. By now you have more than enough context to figure out whether a page you'd care to see in the new docs should be flagged or not.

You know, I have been using open/SUSE for over twenty years, participating in many various ways. If I still have open questions about $SUBJ, I think your explanations may be a bit lacking.

For starters, "whether a page you'd care to see in the new docs" - well, I don't care. That particular page is doing just fine where it is. I don't know what "the new docs" will bring and you have not explained it.

...

If you are still unsure, do just flag it. It won't be difficult to filter out false positives in due time.

Thanks in advance for your help!

Adrien, you appear to be avoiding my main question - if/when it moves out of the wiki, how do I update it?

On 05/08/2021 23.11, Felix Miata wrote:

Adrien Glauser composed on 2021-08-05 22:10 (UTC+0200):

...

How to update migrated contents? Just like you update code: by lodging PRs. As far as I am concerned I have always tried to be receptive to people unfamiliar with git, by accepting Markdown-formatted files and registering a PR for them. What's a PR? What's markdown formatting? They sound like a formula for me never contributing anything other than Bugzilla, forums and mailing lists on opensuse.org ever again. Wikis and Bugzilla I managed to figure out and contribute to. Most things related to how programmers do their things, SVN, Hg, GIT, Gitlab, Github, etc., have had me confounded for over two decades.

Same here. I have written complex wiki pages in full, but I'm not capable of contributing in this new way. Thus I do not want the pages I contributed migrated. -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

On 06/08/2021 07.32, Stefan Seyfried wrote:

On 05.08.21 23:38, Carlos E. R. wrote:

...

I have written complex wiki pages in full, but I'm not capable of contributing in this new way.

It's not rocket science. Markdown is another way of describing content layout, but it is not harder than the myriad of wiki syntaxes. With github / gitlab, there are WYSIWIG markdown editors, so it is about the same skillset that's needed for a Wiki.

The only real difference is, that you usually do not edit the live content but you edit your own private copy (you "fork" the project in your "home project") and then request that your changes are included back in the "official" document (you do a "pull request").

You can do all this from your web browser if you want to. But you can also use powerful tools like "vim", "ed", "NOTEPAD.EXE" to handle the texts.

That's exactly what I feared :-( -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

"+" to all you've said (as the youngsters say it nowadays), Stefan. Thanks for putting that together. A drop of rationality in all this backpressure nonsense is very refreshing for the volunteer in me. Le 06/08/2021 à 13:16, Stefan Seyfried a écrit :

On 06.08.21 11:33, Carlos E. R. wrote:

...

On 06/08/2021 07.32, Stefan Seyfried wrote:

...

On 05.08.21 23:38, Carlos E. R. wrote:

...

I have written complex wiki pages in full, but I'm not capable of contributing in this new way.

It's not rocket science. Markdown is another way of describing content layout, but it is not harder than the myriad of wiki syntaxes. With github / gitlab, there are WYSIWIG markdown editors, so it is about the same skillset that's needed for a Wiki.

The only real difference is, that you usually do not edit the live content but you edit your own private copy (you "fork" the project in your "home project") and then request that your changes are included back in the "official" document (you do a "pull request").

You can do all this from your web browser if you want to. But you can also use powerful tools like "vim", "ed", "NOTEPAD.EXE" to handle the texts.

That's exactly what I feared :-(

What exactly is there to "fear"?

That it is *not* rocket science? So everyone who wants can contribute easily and there is no elite club of Wiki-capable editors anymore? Well, I cannot help with that, but I think it is a good thing!

That you can use a WYSIWIG editor? Don't fear, you can also edit plain text format.

That the changes can be integrated in a coordinated way, and later one can find out who wrote what and maybe ask him what he meant? Don't fear, it's certainly not as adventurous as everyone just editing the result in a chaotic way, but has proven useful in many projects over tme.

That you can use a web browser *or* local editing tools? And work offline? Don't fear, there is no obligation to use a specific set of tools, you can use whatever suits you best. It's actually much more choice than with a Wiki setup.

And IIRC, you are on a volume limited internet connection, so the feature "download (compressed, of course) once, then, in the future, only pull compressed diffs" of the git commandline client might be of some benefit to you!

On 07.08.21 12:42, Carlos E. R. wrote:

On 06/08/2021 13.16, Stefan Seyfried wrote:

...

What exactly is there to "fear"?

That you would propose a not what You See Is What You Get editor, and one that coders love as vim. Terrible idea. Now, if you would propose

You can use both. WYSIWYG editor in the browser at least (probably there are also offline Markdown editors, I never needed one so have not checked this out) and any plain text editor. It does not need to be vim. NOTEPAD.EXE will do just fine, too ;-)

LyX, that would be acceptable.

Sorry, I can not contribute documentation that way.

So a Web-only WYSIWIG editor is fine with the wiki, but not with github? OK.

...

...

That the changes can be integrated in a coordinated way, and later one can find out who wrote what and maybe ask him what he meant? Don't fear, it's certainly not as adventurous as everyone just editing the result in a chaotic way, but has proven useful in many projects over tme.

Same as the Wiki, this is not new.

No, AFAIK most wikis only allow to "hold" changes for review, but is it also possible that multiple people make changes at multiple places in a document at the same time and can these be integrated in a mostly automatic way? I did not yet encounter a wiki with such a feature. And for "find out who wrote what" I can only see a list of "commits" in the wiki like this: https://en.opensuse.org/index.php?title=Main_Page&action=history But I could not find out a way to see "who changed line 443 last?", which is easily done with git: https://github.com/openSUSE/obs-service-tar_scm/blame/master/tar_scm.py (Just a random example). So you'll not lose many editing features as a contributor, but the "manager" of the whole compilation of docs will gain many powerful tools. (I'm not saying "you'll not lose any features", as I do not know all features of the used wiki software). -- Stefan Seyfried "For a successful technology, reality must take precedence over public relations, for nature cannot be fooled." -- Richard Feynman

On 08.08.21 11:40, Carlos E. R. wrote:

On 08/08/2021 11.04, Stefan Seyfried wrote:

...

On 07.08.21 12:42, Carlos E. R. wrote:

...

On 06/08/2021 13.16, Stefan Seyfried wrote:

...

...

What exactly is there to "fear"?

That you would propose a not what You See Is What You Get editor, and one that coders love as vim. Terrible idea. Now, if you would propose

You can use both. WYSIWYG editor in the browser at least (probably there are also offline Markdown editors, I never needed one so have not checked this out) and any plain text editor. It does not need to be vim. NOTEPAD.EXE will do just fine, too ;-)

...

LyX, that would be acceptable.

Sorry, I can not contribute documentation that way.

So a Web-only WYSIWIG editor is fine with the wiki, but not with github? OK.

No, I said editors like vi or (puagh) notepad are "no way". WYSIWIG on line I do not like but I can work with, sometimes.

But the *availability* of editors does not harm you. So I don't understand why you object the possibility of using an editor instead of an web browser.

...

...

...

...

That the changes can be integrated in a coordinated way, and later one can find out who wrote what and maybe ask him what he meant? Don't fear, it's certainly not as adventurous as everyone just editing the result in a chaotic way, but has proven useful in many projects over tme.

Same as the Wiki, this is not new.

No, AFAIK most wikis only allow to "hold" changes for review, but is it also possible that multiple people make changes at multiple places in a document at the same time and can these be integrated in a mostly automatic way? I did not yet encounter a wiki with such a feature.

I meant knowing who wrote what.

And that's pretty hard to find out with wikis AFAIK, becuase they (again, AFAIK) do not have the "svn annotate" / "git blame" functionality. Going through lots of changes one by one is much more tedious than running "git blame foo.md", noting the commit id and then showing who changed what and why. -- Stefan Seyfried "For a successful technology, reality must take precedence over public relations, for nature cannot be fooled." -- Richard Feynman

On 08.08.21 12:48, jdd@dodin.org wrote:

as long as the license is the same, why bother to know who made the change? for problematic topics, there is a discussion page.

Quite often, there is a line in a file (be it code or documentation, it is not really different in this case) which a few years later might seem wrong, outdated or no longer needed. If I stumble across such a line of {code,documentation}, it is very often helpful to ask the original author what this specific piece of {code,documentation} was about, because he might remember the context. And sometimes it is just "Oh, that was probably wrong from the beginning, just drop it", but even then the original author might know best. -- Stefan Seyfried "For a successful technology, reality must take precedence over public relations, for nature cannot be fooled." -- Richard Feynman

On 08.08.21 15:34, jdd@dodin.org wrote:

In a doc, there should not be any "context specific" that is not immediately obvious, so you can change it asap.

One example: You document a workaround to get something working (let's say your bluethooth adapter). One year later, I come around and find that I do not need your work around to get bluetooth working. But was it fixed over time or is it just that my (slightly different) hardware does not nee the workaround yours needs? The easiest way would be to ask the original author of the hint. Finding this person easily is a good thing. Having to go through lots of changes, maybe with not too eloquent changelog messages, is cumbersome.

If you are uncertain of the fact, drop a note in the discussion page for others to see...

Personally, I think the discussion pages are a horrible way to report bugs in a page. Does one even get notified if someone writes something on a discussion page? And how? All the inferior tooling is one of the reasons why I never invested much time into documenting stuff on wikis. Having to use bad tools makes me avoid the work that should be done. So simple. Now I am mostly a developer type of guy, means: I don't really need that documentation. If something does not work, in the worst case, I just look up the problem in the source code ;-) But sometimes when I find a solution to a problem, I actually think about documenting it for others. But in a Wiki page? Where I later probably can not even find it again? No way. In the worst case (for the rest of the community), this documentation just lives on in ~/doc/interesting-problem-with-xxx.txt in my $HOME folder. In the not-so-bad case, I write about it on my blog (which has the additional benefit that later I can find it with any internet search engine ;-)

it's easy and harmless to change some words in a *doc*, it's absolutely not the same for *code*, where a single comma can kill an application

A single wrong instruction can render documentation useless as well, the difference is smaller as you think IMHO. The wrong comma will likely be found by a syntax parser and is obvious and thus easy to fix, but a newbie with wrong documentation about repartitioning his drive might well risk lost data. -- Stefan Seyfried "For a successful technology, reality must take precedence over public relations, for nature cannot be fooled." -- Richard Feynman

On 08/08/2021 16.58, Stefan Seyfried wrote:

On 08.08.21 15:34, jdd@dodin.org wrote:

...

In a doc, there should not be any "context specific" that is not immediately obvious, so you can change it asap.

One example: You document a workaround to get something working (let's say your bluethooth adapter). One year later, I come around and find that I do not need your work around to get bluetooth working. But was it fixed over time or is it just that my (slightly different) hardware does not nee the workaround yours needs?

The easiest way would be to ask the original author of the hint. Finding this person easily is a good thing. Having to go through lots of changes, maybe with not too eloquent changelog messages, is cumbersome.

Often, in the wiki documents, this is not how it goes. The documentation is or was written by a fellow user that went this road before, and documented it for others following. He is not the maintainer, so he has no idea if the code was fixed or your hardware is different. The people to ask would be the coders that wrote that code, if they are reachable.

...

If you are uncertain of the fact, drop a note in the discussion page for others to see...

Personally, I think the discussion pages are a horrible way to report bugs in a page. Does one even get notified if someone writes something on a discussion page? And how?

Yes, you should get an email.

All the inferior tooling is one of the reasons why I never invested much time into documenting stuff on wikis. Having to use bad tools makes me avoid the work that should be done. So simple.

Now I am mostly a developer type of guy, means: I don't really need that documentation. If something does not work, in the worst case, I just look up the problem in the source code ;-) But sometimes when I find a solution to a problem, I actually think about documenting it for others. But in a Wiki page? Where I later probably can not even find it again? No way. In the worst case (for the rest of the community), this documentation just lives on in ~/doc/interesting-problem-with-xxx.txt in my $HOME folder. In the not-so-bad case, I write about it on my blog (which has the additional benefit that later I can find it with any internet search engine ;-)

But no user will find it there :-p Now, if you drop it in the documentation directory of the particular project, then that would be the best place.

...

it's easy and harmless to change some words in a *doc*, it's absolutely not the same for *code*, where a single comma can kill an application

A single wrong instruction can render documentation useless as well, the difference is smaller as you think IMHO. The wrong comma will likely be found by a syntax parser and is obvious and thus easy to fix, but a newbie with wrong documentation about repartitioning his drive might well risk lost data.

In text, a wrong instruction is an entire paragraph with maybe a hundred words. -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

On 08/08/2021 18.57, Stefan Seyfried wrote:

On 08.08.21 18:13, Carlos E. R. wrote:

...

On 08/08/2021 16.58, Stefan Seyfried wrote:

...

On 08.08.21 15:34, jdd@dodin.org wrote:

...

In a doc, there should not be any "context specific" that is not immediately obvious, so you can change it asap.

One example: You document a workaround to get something working (let's say your bluethooth adapter). One year later, I come around and find that I do not need your work around to get bluetooth working. But was it fixed over time or is it just that my (slightly different) hardware does not nee the workaround yours needs?

The easiest way would be to ask the original author of the hint. Finding this person easily is a good thing. Having to go through lots of changes, maybe with not too eloquent changelog messages, is cumbersome.

Often, in the wiki documents, this is not how it goes.

The documentation is or was written by a fellow user that went this road before, and documented it for others following. He is not the maintainer, so he has no idea if the code was fixed or your hardware is different.

But he can answer if this "strange paragraph" in the documentation is still relevant or if he just did forget to remove it 5 versions later when it was no longer relevant.

...

The people to ask would be the coders that wrote that code, if they are reachable.

The developers most likely do not have the specific hardware at hand so they cannot answer if the workaround is still needed.

But don't get hung up on this example.

My opinion is: "Finding out easily who wrote what is useful" Your opionion is: "No, that's totally useless! Nobody would ever want that".

No, I never said that.

I am not going to contribute much to Wiki documentation anyway, so I don't care too much. I *think* that it could be useful if some documentation would be (at least co-)written by the developers and packagers that actually know a lot about the software the docs are about. But -- at least for me -- I will be totally repelled by having to use arcane tooling like web editors for wiki pages, or not being able to easily compare different versions and check for the latest changes.

So good luck with your docs, I probably won't need it anyway.

That's fine! :-D Really, a writer, in this case a wiki writer, loves when the developer documents his stuff. We really do. As long as we can find it. Then all we have to do is link that document, if hard to find; and perhaps complement that documentation with "guides for dummies" or examples for those people that don't understand that documentation. Or, if the documentation is perfect, then fantastic, nothing to write. Just the link. And no, I do not like the wiki editor. I use it because it is there when I'm sufficiently motivated to write something.

...

...

...

If you are uncertain of the fact, drop a note in the discussion page for others to see...

Personally, I think the discussion pages are a horrible way to report bugs in a page. Does one even get notified if someone writes something on a discussion page? And how?

Yes, you should get an email.i

I have written on a few wiki pages, also on the openSUSE wiki, but I never got an email regarding the openSUSE wiki (just looked in my archives of the last 10 years). So either nothing was ever disputed in a talk page or I do not get notifies. Not that I'd fear of missing anything ;-)

I got some. Two in June, two in May. Not from the talk page, but about modifications. ...

...

...

...

it's easy and harmless to change some words in a *doc*, it's absolutely not the same for *code*, where a single comma can kill an application

A single wrong instruction can render documentation useless as well, the difference is smaller as you think IMHO. The wrong comma will likely be found by a syntax parser and is obvious and thus easy to fix, but a newbie with wrong documentation about repartitioning his drive might well risk lost data.

In text, a wrong instruction is an entire paragraph with maybe a hundred words.

Still, if you mix up /dev/sda with /dev/sdb in text, havoc may ensue.

True. So, when someone mentions in somewhere I read that there is such an error in such page, I go and edit it instantly, even if I'm not the person that wrote that. -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

On 09.08.21 20:21, Per Jessen wrote:

Stefan Seyfried wrote:

...

On 08.08.21 15:34, jdd@dodin.org wrote:

...

In a doc, there should not be any "context specific" that is not immediately obvious, so you can change it asap.

One example: You document a workaround to get something working (let's say your bluethooth adapter).

As an example, I would suggest my brief amendment of the article on how to read 1-wire devices on an ARM board.

...

One year later, I come around and find that I do not need your work around to get bluetooth working. But was it fixed over time or is it just that my (slightly different) hardware does not need the workaround yours needs?

When you are so involved anyway, you will probably know, and be able to update the article ?

...

The easiest way would be to ask the original author of the hint.

He may have no idea about your (slightly different) hardware.

You misunderstood. It is me not having his hardware and wondering if his (old? outdated?) workaround can be removed from the documentation.

...

Finding this person easily is a good thing.

Which the wiki supports.

How? I have not found a "svn praise" like function that lists the last-changed author for every line. If it is there, then my remaining complaint would be that it's online-only. Anyway. I think I'm out of this discussion (and probably off this list), as my primary goal is improving *my* mood ;-) -- Stefan Seyfried "For a successful technology, reality must take precedence over public relations, for nature cannot be fooled." -- Richard Feynman

On 08/08/2021 12.42, Stefan Seyfried wrote:

On 08.08.21 11:40, Carlos E. R. wrote:

...

On 08/08/2021 11.04, Stefan Seyfried wrote:

...

On 07.08.21 12:42, Carlos E. R. wrote:

...

On 06/08/2021 13.16, Stefan Seyfried wrote:

...

...

What exactly is there to "fear"?

That you would propose a not what You See Is What You Get editor, and one that coders love as vim. Terrible idea. Now, if you would propose

You can use both. WYSIWYG editor in the browser at least (probably there are also offline Markdown editors, I never needed one so have not checked this out) and any plain text editor. It does not need to be vim. NOTEPAD.EXE will do just fine, too ;-)

...

LyX, that would be acceptable.

Sorry, I can not contribute documentation that way.

So a Web-only WYSIWIG editor is fine with the wiki, but not with github? OK.

No, I said editors like vi or (puagh) notepad are "no way". WYSIWIG on line I do not like but I can work with, sometimes.

But the *availability* of editors does not harm you. So I don't understand why you object the possibility of using an editor instead of an web browser.

No, I object to the idea that I could find enticing the idea of editing plain text with tokens to produce formatting. I find that kind of editing disgusting. I can understand a coder finds that kind of producing formatted text attractive, but a writer does not. You people are happy with vi. The coder type of people. None mentioned editors like LibreOffice writer. That you don't is indicative of a mindset. The closer I can get is LyX, which is related to latex, also a markup editor. -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

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. -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

On 8. Aug 2021, at 14:11, Attila Pinter wrote:

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

...

On Sunday, August 8th, 2021 at 6:52 PM, Carlos E. R. 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_start... 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.

On 8. Aug 2021, at 14:30, Attila Pinter wrote:

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

On Sunday, August 8th, 2021 at 7:23 PM, Richard Brown wrote:

...

...

...

On 8. Aug 2021, at 14:11, Attila Pinter wrote:

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

...

On Sunday, August 8th, 2021 at 6:52 PM, Carlos E. R. 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.

Harder or more steps?

Harder AND more steps When I notice such junk on the wiki, I can just hit edit and correct it. Now I’ll need to fork, make my changes, probably argue with some self appointed reviewers who claim to know better about what is supported despite the fact I’m the one supporting it… Yeah; the more I think about these revamped docs the more insane this whole endeavour seems to be, especially given the total lack of engagement to date with the folk actually in a position of influence on what is “official” and therefore what should be in a curated “official” documentation. I for one like the wiki because it can change in the face of what is “official” as fast as the code can. If our docs have more steps and are harder to contribute to, how can we be sure they aren’t behind what new things have merged in Tumbleweed or MicroOS?

Le 08/08/2021 à 14:44, Andreas Artz a écrit :

IMO it's good to have now the openSUSE Doc and getting the things done with migration etc.

Life is progress and openSUSE as well

sure. But there is something I don't understand. forgive me, I probably haven't read all and any piece of text in this thread... we, of course, have the wiki as documentation but we have also SDB; stuff, which is in the wiki but more syntax oriented. And we have many docs that seems like the old SuSE manual, pretty official (and pretty nice). I don't have an example at hand but I'm sure you know what it is. is the present effort wanting to consolidate all this stuff? If so it could be possible * to keep the same license for all the documentation (probably necessary if you want to copy part of one to the other). We had similar problem when building the Linux Documentation Project wiki (I was in charge then) * to *keep* the wiki, simply replacing a wiki page with a link to the new doc if the new one replaces the old one. * to make some script changing *color* (for example) of wiki pages depending of the last modification date. In Linux time, three years is a very long time. Old pages may be still valuable, but it should be very obvious that the page is old. The main (IMHO) problem with the new system is that we don't know how many people are involved and for how long they will. Organizing the doc is a very huge work, if you want proof reading even more. jdd -- http://dodin.org

Hi everyone, it's good to have this conversation and work through this. Just whatever your position may be, can you *please* take a breath or two and maybe try to put yourself into the shoes of those you are arguing with before your next mail? And refrain from personal attacks or mockery? Let's keep in mind we are largely volunteers here - volunteers who are proposing and working on doc improvements, volunteers who have populated the Wiki, volunteers who rely on our docs and Wiki, plus others who may be just watching at this point or considering (how) to contribute. Discouraging/frustrating volunteers is not anyone's goal, I hope. I assume we all want to make openSUSE better and more welcoming. Can we make sure this shines through in how we handle discourse? Thank you, Gerald -- Dr. Gerald Pfeifer , CTO @SUSE + chair @openSUSE

Nenad Latinović wrote:

We're all adults here, let's talk it out. Otherwise get the board and the gavel and let them decide.

At first I was about to write a longer reply, but then I decided not to. Let us not forget we are a mix of people aged maybe 16 to 88. A crazy mix of gender, education, experience, languages, everything.

But whichever way it is concluded, don't take it personally.

+1. -- Per Jessen, Zürich (20.1°C) Member, openSUSE Heroes

On 09.08.21 20:34, Per Jessen wrote:

Gerald Pfeifer wrote:

...

Discouraging/frustrating volunteers is not anyone's goal, I hope.

I certainly hope it is nobody's goal, but regrettably that is what Adrien's proposal does. It frustrates and discourages volunteers, which is only exacerbated by Adrien apparently being unable to see that.

This also goes the other way round: It's really frustrating (at least for me) to see the old "we always did it like that"-crowd block any progress and discourage any improvement of tools / procedures. Certainly depends on one's POV. (Ooops. I did not want to post again on this list... ;-) -- Stefan Seyfried "For a successful technology, reality must take precedence over public relations, for nature cannot be fooled." -- Richard Feynman

Hello openSUSE! Let me be constructive. I'm not fully clear on the scope of the effort. After long reading it seems to be related to desktop experience. However subject and discussion suggets it's more global than that. Frankly, I'm quite happy for any proactive steps in improving docs quality, or accessible. We did in the past identify that there is tons of docs that need to be "revamped". Meanwhile, I did add docs migration to the agenda of next RelEng call as we maintain quite some documentation. https://etherpad.opensuse.org/p/ReleaseEngineering-20210811#L10 Meeting will be on Wednesday morning. @Adrien, I suppose you're leading the effort, could you please help me to confirm in etherpad bellow whether the referenced docs (in etherpad) are also in scope or totally out of scope? I did list only Leap docs (I'm aware that there are many others, with various content-authors) that we are supposed to maintain, to give you some idea. I'm not saying if it can be easily done, but kit would help identifying next steps that team needs to take. Thank you! I hope that it helps. On Mon, 2021-08-09 at 11:11 +0200, Gerald Pfeifer wrote:

Hi everyone,

it's good to have this conversation and work through this.

Just whatever your position may be, can you *please* take a breath or two and maybe try to put yourself into the shoes of those you are arguing with before your next mail?

And refrain from personal attacks or mockery?

Let's keep in mind we are largely volunteers here - volunteers who are proposing and working on doc improvements, volunteers who have populated the Wiki, volunteers who rely on our docs and Wiki, plus others who may be just watching at this point or considering (how) to contribute.

Discouraging/frustrating volunteers is not anyone's goal, I hope.

I assume we all want to make openSUSE better and more welcoming.

Can we make sure this shines through in how we handle discourse?

Thank you, Gerald

On 08/08/2021 15.26, Stefan Seyfried wrote:

Until today, openSUSE was considered a do-ocracy (at least by me): those who *do*, decide. Apparently this is no longer considered a good idea.

Eum... The wiki is also a do-ocracy. Here we have one do-acracy attempting to destroy another do-acracy. That's something for the community to decide upon, IMO. -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

On 09/08/2021 12.15, Stefan Seyfried wrote:

On 09.08.21 11:49, Carlos E. R. wrote:

...

On 08/08/2021 15.26, Stefan Seyfried wrote:

...

Until today, openSUSE was considered a do-ocracy (at least by me): those who *do*, decide. Apparently this is no longer considered a good idea.

Eum... The wiki is also a do-ocracy.

Here we have one do-acracy attempting to destroy another do-acracy. That's something for the community to decide upon, IMO.

Then what about changing from "Migrating wiki -> new docs" to "Importing wiki -> new docs".

The people who want the wiki can continue to contribute to the wikis, other people will contribute to the new docs. Sooner or later, users will vote with their clicks what documentation fits them best.

It might make "us" (openSUSE Project) look somewhat stupid and disorganized, but that's how we want to be, apparently, so it will properly represent the current state :-)

*If* during the import the "new docs" maintainers find that there is grossly inaccurate or outdated content in the Wiki, they could flag it as such. My personal experience with the Wiki is, that often the information I am looking for is outdated and no longer applies, or that pages are obviously abandoned and unmaintained. A coordinated effort during the import of "looking at all pages" might even benefit the remaining wiki users.

The same effort can be employed at updating the wiki, without creating dispersion. How do we know that the /imported/ articles will still be up to date in five years time? Will be the people updating one site be better at keeping information current that the other people? Why? I don't see why, unless they are a paid team to dedicate full time to writing docs. But in that case, it will happen that they have to explain stuff that they don't know about, and other people have to explain the stuff to them.

Disclaimer: I have not really looked at the wiki for quite some time for obvious reasons -- bad experience in the past. It might of course be all new and shiny today.

It is the same as static information sites. Some pages are current, some are not. Some are written by the developers or maintainers of the stuff they document, others are written by users of that stuff after experimenting with it, without first hand knowledge. For example, the pages I maintain I can only update for each release after I have migrated to the new release and verified the path, so the information is obsolete to the people going there faster than me. So there can be months of delay, even a few years. Will the distribution release be delayed while a documentation team tries and documents in full the new release? I don't think so. Even when obsolete, some pages are informative and of interest to people arriving later that don't know where to start. And perhaps those people can update those pages after getting their goal. On a static site, the barrier for those new people to write something is higher. -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

Dne neděle 8. srpna 2021 14:36:11 CEST, Richard Brown napsal(a):

Now I’ll need to fork, make my changes, probably argue with some self appointed reviewers who claim to know better about what is supported despite the fact I’m the one supporting it… Yeah; the more I think about these revamped docs the more insane this whole endeavour seems to be, especially given the total lack of engagement to date with the folk actually in a position of influence on what is “official” and therefore what should be in a curated “official” documentation.

I think the move can bring plenty of benefits. I agree that doing especially small changes is much faster on wiki. I'd say whole thing could be better discussed from beginning. On the other hand, it's perfect example of openSUSE "do-cracy" - group of active volunteers started to improve one of openSUSE long-lasting issues, which is positive. :-) -- Vojtěch Zeisek https://trapa.cz/ Komunita openSUSE GNU/Linuxu Community of the openSUSE GNU/Linux https://www.opensuse.org/

Vojtěch Zeisek wrote:

Dne neděle 8. srpna 2021 14:36:11 CEST, Richard Brown napsal(a):

...

Now I’ll need to fork, make my changes, probably argue with some self appointed reviewers who claim to know better about what is supported despite the fact I’m the one supporting it… Yeah; the more I think about these revamped docs the more insane this whole endeavour seems to be, especially given the total lack of engagement to date with the folk actually in a position of influence on what is “official” and therefore what should be in a curated “official” documentation.

I think the move can bring plenty of benefits. I agree that doing especially small changes is much faster on wiki. I'd say whole thing could be better discussed from beginning. On the other hand, it's perfect example of openSUSE "do-cracy" - group of active volunteers started to improve one of openSUSE long-lasting issues, which is positive. :-)

I have to wonder if it isn't one of the worst examples of what our "do-ocracy" can lead to. Riding roughshod over the wiki users and authors' community is not a best practice. I also think sensible criticism should be accepted and discussed instead of just arrogantly dismissed as "backpressure nonsense". -- Per Jessen, Zürich (20.2°C) Member, openSUSE Heroes

Vojtěch Zeisek wrote:

Dne neděle 8. srpna 2021 18:29:25 CEST, Per Jessen napsal(a):

...

Vojtěch Zeisek wrote:

...

Dne neděle 8. srpna 2021 14:36:11 CEST, Richard Brown napsal(a):

...

Now I’ll need to fork, make my changes, probably argue with some self appointed reviewers who claim to know better about what is supported despite the fact I’m the one supporting it… Yeah; the more I think about these revamped docs the more insane this whole endeavour seems to be, especially given the total lack of engagement to date with the folk actually in a position of influence on what is “official” and therefore what should be in a curated “official” documentation.

I think the move can bring plenty of benefits. I agree that doing especially small changes is much faster on wiki. I'd say whole thing could be better discussed from beginning. On the other hand, it's perfect example of openSUSE "do-cracy" - group of active volunteers started to improve one of openSUSE long-lasting issues, which is positive. :-)

I have to wonder if it isn't one of the worst examples of what our "do-ocracy" can lead to. Riding roughshod over the wiki users and authors' community is not a best practice.

"Perfect" here doesn't mean "good" in the way everyone would be happy with result, but definitely "good" in a way it shows the principle, which definitely has pros and cons...

Okay, so a perfect example of how it can go wrong? :-)

...

I also think sensible criticism should be accepted and discussed instead of just arrogantly dismissed as "backpressure nonsense".

Well... discussion prior starting of the work wouldn't hurt here, but it happened, so what next?

Nothing irreversible has happened yet. Given the poor way it was approached, including the last-minute "discussion" here, maybe it's a good place to restart the process, beginning with an RFC adressed to all wiki authors. I totally appreciate how discouraging this would be to Adrien and his (apparently) invisible group of people, but I think this proposed migration was 1) approached with complete disregard for the users and 2) has serious potential to decimate our wiki author community.

I'd like to see just one doc.o.o for all documentation - Leap, TW & others, with some option to edit/add/contribute/report problems/... but that'd be another discussion...

It seems to me to be exactly the kind of discussion we could use. -- Per Jessen, Zürich (21.3°C) Member, openSUSE Heroes

Vojtěch Zeisek wrote:

Dne neděle 8. srpna 2021 19:03:55 CEST, Per Jessen napsal(a):

...

...

I'd like to see just one doc.o.o for all documentation - Leap, TW & others, with some option to edit/add/contribute/report problems/... but that'd be another discussion...

It seems to me to be exactly the kind of discussion we could use.

Is this the case when Board should act as discussion moderator?

Oh, if such a discussion is kicked off in a useful manner, I don't think we'll need a moderator. The reason is has gone so badly in the last three-four days is because it was poorly initiated. Adrien wrote:

We want to migrate all relevant contents from the wikis to the new docs, but we don't have time to flip through every single wiki entry.

Nobody had heard anything about this suggestion, and nobody had had any time to think about it. Adrien also failed to present any reason for this proposed move and then he got upset when people were annoyed by the idea. That is bound to end badly. -- Per Jessen, Zürich (18.7°C) Member, openSUSE Heroes

Worry not, we can make sure we steer away from backpressure nonsense with simple steps: 1. you take a look at https://en.opensuse.org/openSUSE:Documentation_migration. 2. you share all the *understanding questions* you still have and the folks from the docs try to address them until there is none left (and I am happy to do my best to address them here). 3. we proceed to *objections*, but since objections are essentially about a team effort, you'll have to share them in a context more hospitable to a debate, where pieces of the context are tightly fitted against each other, so that everyone can appreciate the bigger picture without too much cognitive overload or surrounding noise. That is either the page linked above (section "Discussion"), or the docs ML (because it's more focussed than this one), or our GitHub repository. It's a simple deal: you take the deal, you get answers, you don't take the deal, you don't get answers. You can take it, or you can leave it. That's as much arrogance as I am capable of. Le 08/08/2021 à 18:29, Per Jessen a écrit :

Vojtěch Zeisek wrote:

...

Dne neděle 8. srpna 2021 14:36:11 CEST, Richard Brown napsal(a):

...

Now I’ll need to fork, make my changes, probably argue with some self appointed reviewers who claim to know better about what is supported despite the fact I’m the one supporting it… Yeah; the more I think about these revamped docs the more insane this whole endeavour seems to be, especially given the total lack of engagement to date with the folk actually in a position of influence on what is “official” and therefore what should be in a curated “official” documentation.

I think the move can bring plenty of benefits. I agree that doing especially small changes is much faster on wiki. I'd say whole thing could be better discussed from beginning. On the other hand, it's perfect example of openSUSE "do-cracy" - group of active volunteers started to improve one of openSUSE long-lasting issues, which is positive. :-)

I have to wonder if it isn't one of the worst examples of what our "do-ocracy" can lead to. Riding roughshod over the wiki users and authors' community is not a best practice.

I also think sensible criticism should be accepted and discussed instead of just arrogantly dismissed as "backpressure nonsense".

Okay Per, if your main priority is to work with us together, we can talk live in the bar or something. But I think we are not compatible for text-base interactions so I'll let it go. You won't get any written reply from me ever again unless through mediation. Could be someone from the docs willing to substitute for me, could be the Board. Anything goes. Good night, and good luck. Le 08/08/2021 à 19:40, Per Jessen a écrit :

Adrien Glauser wrote:

...

Worry not, we can make sure we steer away from backpressure nonsense with simple steps:

That attitude only makes me worry even more. You should not consider reasonable opposition and feedback as "backpressure nonsense" and try to steer away from it, what sort of attitude is that?

There are clearly people here who have grave concerns about this proposed migration, a migration that they had never even heard of until a few days back.

...

1. you take a look at https://en.opensuse.org/openSUSE:Documentation_migration.

I beg your pardon, but that is a load of nonsense.

Q: "What is the rationale behind the migration?" A: "The migration has been justified in details here", "here" being your initial post to the project list.

Your initial post presents _no_ rationale whatsoever. You only asked for help. The page above was created three days ago, _after_ you had already asked for help. Second, your initial request for help was way back in January 2021, to doc.lists :

https://lists.opensuse.org/archives/list/doc@lists.opensuse.org/thread/VMM6B...

I cannot find it, but I presume you explained the rationale in an earlier posting, back in 2020. One issue is - doc.lists is primarily official documentation, not for the wikis. I have cross checked the list of subscribers with the list of wiki authors, and there is virtually no overlap.

...

2. you share all the *understanding questions* you still have and the folks from the docs try to address them until there is none left (and I am happy to do my best to address them here).

Who are these "folks from the docs" ? I thought you said they were not subscribed here.

...

3. we proceed to *objections*, but since objections are essentially about a team effort, you'll have to share them in a context more hospitable to a debate,

I find this context perfectly suited.

...

where pieces of the context are tightly fitted against each other, so that everyone can appreciate the bigger picture

Has anyone actually presented the bigger picture, ever?

...

without too much cognitive overload or surrounding noise. That is either the page linked above (section "Discussion"), or the docs ML (because it's more focussed than this one), or our GitHub repository.

Objection - you do not get to tell us where to discuss this project, especially after you have neglected to inform us about it (until three days back). I suggest this ML is perfectly well suited for this discussion, the members are largely committed community members of many years.

...

It's a simple deal: you take the deal, you get answers, you don't take the deal, you don't get answers. You can take it, or you can leave it. That's as much arrogance as I am capable of.

IOW, no shortage on arrogance. You also continue to top post, something that violates openSUSE netiquette and is generally frowned upon.

On 09/08/2021 21.42, Per Jessen wrote:

Adrien Glauser wrote:

...

Okay Per, if your main priority is to work with us together, we can talk live in the bar or something.

Adrien, my main/only priority is the openSUSE community. If my own wiki articles and amendments end up somewhere else, it does not hurt me, but I worry it might hurt the community (not that my writings are all that amazing).

...

But I think we are not compatible for text-base interactions so I'll let it go. You won't get any written reply from me ever again unless through mediation.

The mind boggles. In thirtytwo years of using email and other text-based systems, communicating with people around the globe, I have never ever met anyone who felt "incompatible" with me. Meeting up in person has always improved relations, no doubt about that, but communications has also always worked just fine without it.

I admit however, I am utterly frustrated at your lack of response to questions and concerns expressed here on the list, right from the beginning.

I also admit I find it extremely arrogant to ignore subtle hints about top-posting and just persevere.

+1 to all. -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

On 8/9/21 3:10 AM, Per Jessen wrote:

Adrien Glauser wrote:

...

Worry not, we can make sure we steer away from backpressure nonsense with simple steps:

...

3. we proceed to *objections*, but since objections are essentially about a team effort, you'll have to share them in a context more hospitable to a debate,

I find this context perfectly suited.

As I have said elsewhere here I agree with Per, this sort of discussion is exactly what this list was created for, this discussion clearly expands beyond the docs team to the broader project as such this is the right place for discussion, people shouldn't need to join yet another mailing list just to provide feedback. -- Simon Lees (Simotek) http://simotek.net Emergency Update Team keybase.io/simotek SUSE Linux Adelaide Australia, UTC+10:30 GPG Fingerprint: 5B87 DB9D 88DC F606 E489 CEC5 0922 C246 02F0 014B

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/78f6e2b9e08792d... [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 wrote: ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

On Sunday, August 8th, 2021 at 6:52 PM, Carlos E. R. 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_start...

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.

On Sun, Aug 8, 2021, at 22:51, Richard Brown wrote:

...

On 8. Aug 2021, at 21:49, Syds Bearda wrote:

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.

And so, you admit that you knowingly added to the wannabe “official” docs stuff that you knew would never be officially supported?

What does “officially supported” mean in the case of openSUSE or MicroOS? You have already stated numerous times (to me) you don’t support anything anyway. The only thing you do is work on what you want and nothing else. Also when I see questions regarding the desktop version come up on Telegram/ Discord or Matrix I’m usually one of the first few answering the question. To me that is support and I enjoy helping people in using something I think is a great distribution. Only thing I can’t call it is official support, as I have no idea what that means in terms of open source where you don’t pay anyone to help you..

Do you not see how your actions fully undermine any premise of this endeavour improving the quality of openSUSE documentation?

No, I see them as an improvement over what you think is the necessary minimal documentation. Even to be completely honest, because of your bully attitude I already knew contributing to the MicroOS wiki directly was a bad idea, I don’t point people towards it and I don’t read them. I have also never sent anyone your way to answer a question. Is that the situation and environment you want to create? Having a third party reviewer accepting or commenting on changes to these docs is a very good idea in my eyes.

Sure the wiki can have you or anyone else post equally unofficial nonsense, but at least then people know it’s a wiki and it’s easy to correct.

When you say correct, do you mean delete? Cause it sure as hell feels like you do.. And thanks again for calling my contribution nonsense. Makes me feel really happy to be here. Especially since that contribution has helped many people already.

The whole premise of these revamped docs is that it should be better and somehow “more official” than the current wiki.

If that’s the case; all mention of snaps and virtualbox on MicroOS have no place on there, at all.

Again your opinion. But I have been asked this question before. Snaps are not unreasonable as it’s also a containerised solution. And VirtualBox is just a VM tool that actually works better than Gnome Boxes and I tried QEMU but it has less to offer for me. Only time I had an issue with VirtualBox was when we moved to the 5.13 kernel, but that got fixed pretty soon after and was discussed on the project ML, never on the kubic ML.

All mention of KDE on MicroOS has no place there either - it doesn’t matter if people use it, it’s 100% unmaintained.

Last I heared about KDE maintaince is that we have one person working on that. Did something change?

If the MicroOS docs on the revamped docs page are meant to be representative on how this effort will be improving the quality of the openSUSE docs, then let’s stick with the Wiki.

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

...

On 8. Aug 2021, at 21:49, Syds Bearda wrote:

...

- 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.

There are hundreds, if not thousands of packages in Tumbleweed that do not work properly on Transactional systems.

You should never assume just because it builds for Tumbleweed it will be supported on MicroOS

I never assumed they would all work, I’ve tested and experimented if some worked. Those that worked I’ve written down how to make them work. Those that don’t work I have not written down. But for example the PIA self installer script does not work..

As the official MicroOS docs state , it’s designed for container and edge use cases.

I know the designed use. I’m trying to get it to a higher level, as I feel immutable OS is the future and MicroOS is the best option for that in my eyes.

And we have a GNOME desktop in beta.

Everything else is unsupported. Period.

And that’s fine, experiment, have fun, it’s openSUSE after all - but don’t put any of that anywhere near any documentation that remotely attests to be “official”

To do so is unfair on the developers who develop MicroOS and who know exactly what they are willing to support on the OS they are developing.

So this is the real issue. You assume that because I wrote something down you have to do work. While I already know you don’t do things you don’t want to, so what is your issue here?

A first note before reading the rest. I’m not trying to pick a fight with you. I just disagree with you on this and want to make myself clear. Also I’m not standing by while I feel I’m being attacked on something I feel is helpful and has helped many people already. On Mon, Aug 9, 2021, at 09:26, Richard Brown wrote:

...

On 9. Aug 2021, at 07:41, Syds Bearda wrote: So this is the real issue. You assume that because I wrote something down you have to do work. While I already know you don’t do things you don’t want to, so what is your issue here?

I’m the release manager for MicroOS

Okay, thank you for that. This is for real btw. I am for real grateful that you started MicroOS as I see great potential for it. On a side note though. Who or where did you get appointed release manager for MicroOS. Was there an election or is this self appointed?

If you do write something down and declare it officially supported, I will have to do that work.

Where do I write officially supported. I never say that nor do I know what officially supported means in the case of MicroOS. Could you please elaborate on that because you keep saying official support and I have no idea what that means.

I will have to triage those bugs.

Have you actually received bugs for it? Have I ever posted a bug for you on MicroOS?

I will need to accept those pull requests to the core parts of the distro.

Yeah where we had discussions before and where you threatened to remove stuff you don’t use but I do, just because you don’t want more work. Which is a bully attitude to begin with.

I will need to juggle the growing integration problems the more complex support base requires.

One of the absolute core points of MicroOS is that it has a narrower scope than the rest of Tumbleweed.

Are you the sole decider of this?

One of the reasons for that is to be able to provide a very narrowly focused, opinionated, polished experience to its users.

Another one of those reasons is to be able to provide that narrowly focused, opinionated, polished experience with a minimal amount of effort by a minimal amount of people.

If more people were actively actually helping on “in the muck”, actually triaging bugs with me, actually fixing packages/patterns (not just throwing changes over the wall and ignoring feedback), actually handling the integration issues that need to be fixed to support some of this stuff.. then sure, MicroOS can have a broader scope and the documention can reflect that.

I am trying to help in the muck, but my skill set is not within the code but trying and experimenting ways to help someone. If someone asks if snaps work I can at least say, that they could work but they are not supported, but this is (Btw with supported I mean both TW and MicroOS, as they are not even in the official repo). I’ve even suggested pattern changes in the beginning to remove certain suggested install packages from my manual. But that was shot down really strongly from you and made me realise my contributions are better with the manual and actually helping people when they have a question on telegram/ matrix and discord than going into discussions with you.

But you accuse me of bullying while you write so-called “official” documentation that puts more work on my shoulders? Please, stop.

I’m not accusing you of being a bully. I said you have a bully attitude toward me and a lot more people who have started to contribute to openSUSE since I’ve started a year ago. A bully can’t really change their ways, but an attitude you can change and by me calling it out I hoped you would see where I’m coming from. Because all I hear is that you think everything you do is right and nobody else can have a say or is even allowed to have a different opinion. Also do you realise I’m not the first person calling you out on your bully attitude King Richard?

The only official documentation for MicroOS is at https://microos.opensuse.org/ and will remain so for the foreseeable future.

Can you please continue this conversation about our microOS documentation in a more relevant place? I've opened this issue so that your technical expertise can be made the best use of: https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/16 Le 09/08/2021 à 10:30, Richard Brown a écrit :

On Mon, 2021-08-09 at 09:54 +0200, Syds Bearda wrote:

...

A first note before reading the rest. I’m not trying to pick a fight with you. I just disagree with you on this and want to make myself clear. Also I’m not standing by while I feel I’m being attacked on something I feel is helpful and has helped many people already.

On Mon, Aug 9, 2021, at 09:26, Richard Brown wrote:

...

...

On 9. Aug 2021, at 07:41, Syds Bearda wrote: So this is the real issue. You assume that because I wrote something down you have to do work. While I already know you don’t do things you don’t want to, so what is your issue here?

I’m the release manager for MicroOS

Okay, thank you for that. This is for real btw. I am for real grateful that you started MicroOS as I see great potential for it.

On a side note though. Who or where did you get appointed release manager for MicroOS. Was there an election or is this self appointed?

MicroOS started life as a SUSE-sponsored direct contribution to openSUSE alongside SUSE's development of the SUSE CaaSP (and now SLE Micro) commercial projects.

My role as a contributor in this openSUSE side project was 'appointed' by the team/SUSE.

...

...

If you do write something down and declare it officially supported, I will have to do that work.

Where do I write officially supported. I never say that nor do I know what officially supported means in the case of MicroOS.

You put it in documentation that wants to be official, telling people what is the official way of doing things in openSUSE.

"Officially supported" means aligned with the goals of the contributors to MicroOS. This means (ideally all of the below):

- is tested - is managed as part of the MicroOS/Tumbleweed release process (ie. no third party repos) - is aligned with the types of bugs the contributors involved are willing to resolve

your documentation for MicroOS does not comply with any one of those standards

...

Have you actually received bugs for it? Have I ever posted a bug for you on MicroOS?

MicroOS recieves a number of bugs that are out of intended scope of MicroOS - examples:

https://bugzilla.opensuse.org/show_bug.cgi?id=1184385 https://bugzilla.opensuse.org/show_bug.cgi?id=1171177 https://bugzilla.opensuse.org/show_bug.cgi?id=1166157 https://bugzilla.opensuse.org/show_bug.cgi?id=1137460

MicroOS also recieves a number of bugs which clearly affects users but no one takes effort to fix or reply to - examples:

https://bugzilla.opensuse.org/show_bug.cgi?id=1188957 https://bugzilla.opensuse.org/show_bug.cgi?id=1188110 https://bugzilla.opensuse.org/show_bug.cgi?id=1184411 https://bugzilla.opensuse.org/show_bug.cgi?id=1185647

both sets of examples above stand as justification for NOT broadening the scope of MicroOS further and not documenting unofficial/unsupported/unmaintained workflows.

We have enough to keep us busy with what we are willing and able to support.

...

...

I will need to accept those pull requests to the core parts of the distro.

Yeah where we had discussions before and where you threatened to remove stuff you don’t use but I do, just because you don’t want more work. Which is a bully attitude to begin with.

Look at it from my point of view

1. I accepted something expanding the scope of MicroOS on the promise of a contributor (not you) that it would be supported and/or it wouldn't produce extra work for me.

2. Contributor dissapears/contributions dry up. That stuff becomes unmaintained.

3. You approach me, producing work for me (dealing with you is work, even when it's pleasent).

4. I am not willing, nor able to fix the thing, I don't use the thing, so the only option really available to me is to remove the thing given no one is there to maintain it and its producing more work for me.

It's not bullying, it's actually long overdue and needed maintainance.

...

...

...

I will need to juggle the growing integration problems the more complex support base requires.

One of the absolute core points of MicroOS is that it has a narrower scope than the rest of Tumbleweed.

Are you the sole decider of this?

No. As described, MicroOS started as a SUSE-sponsored contribution to openSUSE, and the team includes people like Thorsten Kukuk (SUSE's MicroOS Architect, and my boss) who defined the original scope of MicroOS.

Since MicroOS has been in openSUSE there has been some allowance of scope creep - for example the MicroOS Desktop is a clear example of a community contribution (me in my spare time) doing something way outside of the intended scope of MicroOS, over the objections of Thorsten.

In the case of GNOME I think we can make an argument that it's been worth the effort, has gained additional contributors, does (slowly) move forward, even though we haven't made something good enough to get out of BETA yet.

In the case of KDE, I have to admit Thorsten was utterly right and I should have listened to him and not allowed it to happen.

...

I’ve even suggested pattern changes in the beginning to remove certain suggested install packages from my manual. But that was shot down really strongly from you and made me realise my contributions are better with the manual and actually helping people when they have a question on telegram/ matrix and discord than going into discussions with you.

But are you really helping the MicroOS Project if you document things out of scope of what the MicroOS contributors are contributing?

I'd argue it's more problematic than a help, while I do appreciate the thought.

...

Also do you realise I’m not the first person calling you out on your bully attitude King Richard?

If you haven't noticed already, I typically don't respond to any ML posts that resort to namecalling. I made an exception in this case.

On 09.08.21 09:26, Richard Brown wrote:

The only official documentation for MicroOS is at https://microos.opensuse.org/ and will remain so for the foreseeable future.

That's totally fine, and I'd guess Syds would happily accept a pullrequest to his documentation that adds a top banner telling everyone where the "official" documentation is, that his documentation is inofficial. And he then can add the runner-up "... but useful" ;-) -- Stefan Seyfried "For a successful technology, reality must take precedence over public relations, for nature cannot be fooled." -- Richard Feynman

On 08/08/2021 15.11, Stefan Seyfried wrote:

On 08.08.21 13:24, Carlos E. R. wrote:

...

On 08/08/2021 12.42, Stefan Seyfried wrote:

...

...

But the *availability* of editors does not harm you. So I don't understand why you object the possibility of using an editor instead of an web browser.

No, I object to the idea that I could find enticing the idea of editing plain text with tokens to produce formatting. I find that kind of editing disgusting.

Then just use the WYSIWYG editor. What's the problem with the *availability* of tools?

It is not the availability of tools, but the fact that you consider that /I/ could use vi (or (gah) notepad) to edit a document with some kind of advanced format. Again, I understand a coder likes the idea, but not a writer and you have to understand that. Yet another markdown language to learn? No way. For a similar reason, I don't translate man pages, and practically nobody does. The majority of man pages are not translated. Hey, this is another question for the project: what do you intend to do to translate man pages? And now that I think about this, will this new documentation be translated, and how? What about availability of offline tools to work in a WYSIWYG or WYMIWYG manner on markdown documents? If I google "what is markdown text" the first hit is "Getting Started | Markdown Guide" at https://www.markdownguide.org/getting-started/, and the first editor I'm offered is "Visual Studio Code text editor", not vi. Then it goes on to suggest tools that have the editor on the left pane and the rendered text on the right. For Linux it suggests ReText or ghostwriter, not vi, although I don't see photos. Ah, some photos of the later: https://wereturtle.github.io/ghostwriter/

...

You people are happy with vi. The coder type of people. None mentioned editors like LibreOffice writer. That you don't is indicative of a mindset.

I would not be surprised if you could even edit markdown documents with LibreOffice nowadays. I would not install hundreds of megabytes of stuff to test this, though ;-)

-- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

On 08/08/2021 19.03, Vojtěch Zeisek wrote:

Dne neděle 8. srpna 2021 18:49:16 CEST, Carlos E. R. napsal(a):

...

On 08/08/2021 15.11, Stefan Seyfried wrote:

...

On 08.08.21 13:24, Carlos E. R. wrote:

...

On 08/08/2021 12.42, Stefan Seyfried wrote:

...

But the *availability* of editors does not harm you. So I don't understand why you object the possibility of using an editor instead of an web browser.

...

...

No, I object to the idea that I could find enticing the idea of editing plain text with tokens to produce formatting. I find that kind of editing disgusting.

...

Then just use the WYSIWYG editor. What's the problem with the *availability* of tools?

It is not the availability of tools, but the fact that you consider that /I/ could use vi (or (gah) notepad) to edit a document with some kind of advanced format.

How did You edit wiki? MD is very similar to wiki, I'd say.

MD? Sorry, what is MD? [...] Ah, markdown, ok.

...

And now that I think about this, will this new documentation be translated, and how?

This was already answered: weblate.

Was it? Sorry, I did not notice. [... searching... found:] VZ>> 2) Will there be any possibility to translate the content? Adrien> Yes, weblate. I am dodging any discussion about this because there are too many milestones to cross before that becomes a subject. Ok, so then not a solved or even thought in depth issue. No problem for me, I was just curious whether it had been decided and the translators contacted. -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

On 08/08/2021 19.16, Stefan Seyfried wrote:

On 08.08.21 18:49, Carlos E. R. wrote:

...

On 08/08/2021 15.11, Stefan Seyfried wrote:

...

On 08.08.21 13:24, Carlos E. R. wrote:

...

On 08/08/2021 12.42, Stefan Seyfried wrote:

...

...

But the *availability* of editors does not harm you. So I don't understand why you object the possibility of using an editor instead of an web browser.

No, I object to the idea that I could find enticing the idea of editing plain text with tokens to produce formatting. I find that kind of editing disgusting.

Then just use the WYSIWYG editor. What's the problem with the *availability* of tools?

It is not the availability of tools, but the fact that you consider that /I/ could use vi (or (gah) notepad) to edit a document with some kind of advanced format.

"You could" in the sense that "you would have the option to". I'm not sure if "our problem" here right now is just a language problem, both of us not being native english speakers? "You would have the option to use an editor if you wanted."

...

Again, I understand a coder likes the idea, but not a writer and you have to understand that. Yet another markdown language to learn? No way.

I never suggested you *should* use an external editor. You would have the option to just use the WYSIWYG web editor, similar to the wiki.

...

For a similar reason, I don't translate man pages, and practically nobody does. The majority of man pages are not translated.

Hey, this is another question for the project: what do you intend to do to translate man pages?

And now that I think about this, will this new documentation be translated, and how?

This could maybe crowd-sourced with platforms like transifex

...

What about availability of offline tools to work in a WYSIWYG or WYMIWYG manner on markdown documents?

Do you have an offline tool for the wiki?

No, I'm not aware.

If not, how is this relevant to our discussion?

Because the first tool that was mentioned here was vim, offline.

...

If I google "what is markdown text" the first hit is "Getting Started | Markdown Guide" at https://www.markdownguide.org/getting-started/, and the first editor I'm offered is "Visual Studio Code text editor", not vi. Then it goes on to suggest tools that have the editor on the left pane and the rendered text on the right. For Linux it suggests ReText or ghostwriter,

retext and ghostwriter are readily available via "zypper in"

Good.

...

not vi, although I don't see photos.

I also did not suggest vi as "markdown editor". I do not understand how you come to this conclusion. All I wanted to say is "it's just text, you can edit it with *any* editor, even NOTEPAD.EXE" (which of course is not meant seriously). And contrary to HTML and other markup languages, Markdown is pretty readable even as plain text. This is why I do not use a special "markdown editor", it's just good enough in $EDITOR and the few syntax elements I need I can type faster than select them from some menu.

I know you do :-) But as I said, please understand that this type of writing puts me off. I'm not willing to learn "yet another markdown" language. Yes, even WordStar back in 1985 was a markdown editor. I could properly edit and format documents by just looking at the "code" it produced. I don't want a new one, no matter how easy it is.

But of course it also works with a "markdown editor". If you do not want to install one, just use the github or gitlab or whatever platform we'll be using web editor. They are all usable nowadays, I'd guess the feature difference to the mediawiki editor is not too huge (but I have not recently compared them).

-- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

On 10/08/2021 06.04, Attila Pinter wrote:

On Tuesday, August 10th, 2021 at 6:33 AM, Carlos E. R. <> wrote:

...

On 08/08/2021 19.16, Stefan Seyfried wrote:

...

On 08.08.21 18:49, Carlos E. R. wrote:

...

...

...

What about availability of offline tools to work in a WYSIWYG or WYMIWYG

manner on markdown documents?

Do you have an offline tool for the wiki?

No, I'm not aware.

...

If not, how is this relevant to our discussion?

Because the first tool that was mentioned here was vim, offline.

The beauty of this is that you can use any tool you want to. I like to use VSCode, vim, but lately I use a flatpak application called Apostrophe which I love. If you want to write in LibreOffice Writer or Notepad++ or Kate or Mousepad or Nano or whatever it is could even make a branch and add a doc on code-o-o/github and edit there. Absolutely possible to do so and nobody would "force" you to use xyz tool to write your docs/articles. Nobody is excluded.

Appreciated. My only remaining big caveat (I don't know if I'll participate writing documentation) is that I strongly think that every migrated wiki page must have an entry in the new doc listing the contributors of the original wiki page. Not a combined reference to all the contributors to the entire wiki, but those of the current page. After all, they are the ones that at least knew about the current subject and might be asked. It is the fair thing to do. And you have seen that even some board members and ex board members think similarly. Eum.... something else... could I suggest that you (plural) improve your email manners? It is something that puts seasoned people off and has been mentioned before in this thread :-) https://en.opensuse.org/openSUSE:Mailing_list_netiquette For example, your email has a lot of quoted material, even after the small paragraph you wrote. This slows up reading and puts people a bit off. Adrien has the habit of top posting, and that is considered by many, in different degrees, as offensive, after been told. I'm aware, though, that some mail clients, specially webmail clients, make this difficult by hiding the quoted text. I'm also aware that people new to a particular mail list (or group of them) may not know the local netiquette rules. Most people are tolerant, but also most expect acceptance of the "rules" after mentioning them. I also was once a newcomer and had to adapt to the local culture. Otherwise, flames ensue. (yes, other mail lists may have different culture or netiquete) I guess you may suggest video conferencing. This poses new problems: - Finding a suitable time slot for everybody. - Not everybody is fluent in English. I am, but I have problems understanding each person accent, and it takes me a long time to adjust; meanwhile, I lose content. - Not everybody has the hardware. For example, the machine I have to use this summer is not capable of handling Jitsi (https://meet.opensuse.org), not powerful enough. - Email communication can be used anytime of the day and leaves a record. No fixed hour to be attending. No limit on attendance. - Even if recorded, video can not be searched, unless someone takes minutes (and every participant later signs them). -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))

Stefan Seyfried wrote:

On 07.08.21 12:42, Carlos E. R. wrote:

...

On 06/08/2021 13.16, Stefan Seyfried wrote:

...

...

What exactly is there to "fear"?

That you would propose a not what You See Is What You Get editor, and one that coders love as vim. Terrible idea. Now, if you would propose

You can use both. WYSIWYG editor in the browser at least (probably there are also offline Markdown editors, I never needed one so have not checked this out) and any plain text editor. It does not need to be vim. NOTEPAD.EXE will do just fine, too ;-)

...

LyX, that would be acceptable.

Sorry, I can not contribute documentation that way.

So a Web-only WYSIWIG editor is fine with the wiki, but not with github? OK.

I think there are probably openSUSE wiki contributors who have little or no idea what github is or how it works. Will our openSUSE logins work on github?

No, AFAIK most wikis only allow to "hold" changes for review, but is it also possible that multiple people make changes at multiple places in a document at the same time and can these be integrated in a mostly automatic way? I did not yet encounter a wiki with such a feature.

wikipedia? as for "multiple people make changes at multiple places in a document at the same time", TMK that has never been an issue. With even fewer contributors, it will likely never become an issue.

So you'll not lose many editing features as a contributor, but the "manager" of the whole compilation of docs will gain many powerful tools. (I'm not saying "you'll not lose any features", as I do not know all features of the used wiki software).

To me, the one key feature is the speed of making changes. find page, edit, make change, save. If that is retained with the move, including my openSUSE login, I have no issues. -- Per Jessen, Zürich (19.1°C) Member, openSUSE Heroes

Le 05/08/2021 à 22:10, Adrien Glauser a écrit :

How to update migrated contents? Just like you update code:

but many documentation providers are not coders... does wikipedia asks for such thing? sorry jdd -- http://dodin.org

Adrien Glauser wrote:

How to update migrated contents? Just like you update code: by lodging PRs.

I did suspect as much.

As far as I am concerned I have always tried to be receptive to people unfamiliar with git, by accepting Markdown-formatted files and registering a PR for them.

It sounds like you have added one-two extra steps in the process - compared to the three-step wiki process of clicking edit, writing some text, and hitting save. IMHO, that is not conducive to more user-created content - which I believe is an important way of involving more people. Anyway, good luck with the project. -- Per Jessen, Zürich (23.4°C) Member, openSUSE Heroes

As far as I am concerned yes. I have nothing to say for or against these pages.

Hi, O/n 04/08/2021 16.37, Adrien Glauser wro/te:

...

1) What is/will be relationship to https://doc.opensuse.org/? Perhaps, I haven't heard anything from the folks in charge of it.

I guess I am a person who's in charge of it (to a degree anyway).

From the user's perspective it would be good to have everything hosted there.

Soo... I think adding the content currently on GH Pages to DOO is not an issue. But I think there's still a bit of an organizational question in terms of how the new content will relate to/coexist with the existing content.

...

3) How will contribution be possible? By pull request using git? Contrary to doc.opensuse.org and to the wikis, there will be -- at least while I am alive -- maintainers. So you get the best of both worlds (updated, peer-reviewed).

For the record, DOO _is_ maintained by the SUSE doc team. The level of maintenance is probably not ideal, nevertheless the bit about there being no maintenance is just wrong. We also do enable contributions to existing openSUSE (Leap) docs via https://github.com/suse/doc-sle. I can see how from an openSUSE community perspective, it may be a bit weird that that is the same repo that is also used for the SLES/SLED/SLE Micro docs. Given the similarity between the projects/products, it does make sense, however. We have also recently started a project trying to go in a similar direction as this project, but in the context of the SLE documentation, i.e. article/tutorial-style docs. I guess there might turn out to be some topical overlap. hth Stefan. -- SUSE Software Solutions Germany GmbH: Maxfeldstraße 5 / 90409 Nürnberg/ Germany. HRB 36809, Amtsgericht Nürnberg. Geschäftsführer: Felix Imendörffer.

On 6. Aug 2021, at 13:24, Stefan Seyfried wrote:

On 06.08.21 11:44, Richard Brown wrote:

...

As one of the many copyright holders who contributed under the GFDL I would strongly object to any relicensing of my contributions to the openSUSE wiki.

*any* relicensing? No matter what the new license is?

Generally speaking, yes. I typically take care to consider which licenses I contribute under and shy away from any CLA or other mechanism for allowing relicensing. I would consider it if I, along with all other license holders, are approached and asked nicely but that does not seem to be consistent of the modus operandi of those orchestrating this migration.

...

Note: the doc.opensuse.org sources are licensed diferently with the full blown GPLv3 license:

GPLv3 would be unacceptable for your contributions as a new license? Why?

Well I outright refuse to contribute to any “GPLvX or later” licensed software as the “or later” clause gives the FSF rights to change the GPL in future versions and have them apply to those old code bases. Considering the FSFs terrible judgement in its leadership decisions lately I think that’s understandable. While I am less hardline on the GPLv3 generally, I still typically shy away from it because it contains clauses that govern how a user may use the licensed software. I also think the GPLv3 is a bloody stupid license for use for documentation. Regardless though, your point is irrelevant to the topic at hand - the wikis license and doc.openSUSE.orgs license are different with competing clauses, and anyone trying to merge both licensed works together needs to do the footwork to honour the licenses of the existing works, with the consent of the affected copyright holders. Any talk of actually migrating any content to a new platform before that is done is premature at best or a potential license infringement at worst.

On 8/6/21 8:53 PM, Stefan Seyfried wrote:

On 06.08.21 11:44, Richard Brown wrote:

...

As one of the many copyright holders who contributed under the GFDL I would strongly object to any relicensing of my contributions to the openSUSE wiki.

*any* relicensing? No matter what the new license is?

Any form of relicensing is exceptionally difficult as it requires permission from all former contributors, on a page by page basis this is probably possible for some pages but given others have 10 years of history there is a significant chance that its not even possible to contact everyone anymore as such its probably much safer to just license the new docs under the same license as the wiki docs. This is the main reason i'm reluctant to permit a license change on my contributions unless someone can give a really good reason. -- Simon Lees (Simotek) http://simotek.net Emergency Update Team keybase.io/simotek SUSE Linux Adelaide Australia, UTC+10:30 GPG Fingerprint: 5B87 DB9D 88DC F606 E489 CEC5 0922 C246 02F0 014B

Le 07/08/2021 à 07:49, Syds Bearda a écrit :

Just wondering as someone with no experience in the legalities of these licenses, but why do the wiki and docs need to be licensed at all?? And why do you (anyone) care what the licence would be?

copyright laws are made so any text with no licensing is only owned by he's author! so if no license is given, no modification can be made :-( I helped write this page time ago :-) https://wiki.tldp.org/WikiAuthorGuide#Licence jdd -- http://dodin.org

Dear Richard, Thanks for your email. This is utterly offtopic but it's a good point I'll be pleased to talk with you about in private or publicly if you open a Git Issue or a new topic. I will not pursue this topic here. Best, Adrien Le 06/08/2021 à 11:44, Richard Brown a écrit :

On Wed, 2021-08-04 at 15:53 +0200, Adrien Glauser wrote:

...

Hi folks,

We want to migrate all relevant contents from the wikis to the new docs, but we don't have time to flip through every single wiki entry.

The help would be: 1) identify relevant contents 2) flag / mark the relevant contents on the wikis that they are going to be migrated 3) report to us and help us migrate gracefully (i.e. check the contents, format them, merge them, and finally replace them on the relevant wiki pages with a single link pointing to their new location)

Dear Adrien,

The openSUSE wiki is licensed under GNU Free Documentation License version 1.2 ("GFDL")

Source: https://en.opensuse.org/Terms_of_site

The new documentation site has no license as far as I can find:

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

If this is your intent, this would consistute a relicensing of the content of the openSUSE wikis.

As one of the many copyright holders who contributed under the GFDL I would strongly object to any relicensing of my contributions to the openSUSE wiki.

Note: the doc.opensuse.org sources are licensed diferently with the full blown GPLv3 license:

https://github.com/openSUSE/doc-o-o/blob/main/LICENSE

If you intend to merge content from docs.opensuse.org and the wikis, how you rectify that discrepancy to be able to honour the terms of both licenses is a challenge you will need to tackle.

Regards,

By offtopic, I mean: "is better handled in its own completely separated conversational context", for 3 reasons: - half of the problem is solved already after a recent commit to the new docs, whereas the other half of the problem will be solved with people from doc.opensuse.org, which we are set to meet next week; - the topic of this thread is: 'How can I help the volunteers working on the revamped docs deprecating & migrating wiki contents?' - it's part of communication best-practice and frankly common decency to target key presuppositions against which an ongoing conversation is building in a separate conversational context, even more so when the conversation has been running for some time, so as to not torpedo that conversation. I'll be my pleasure to alleviate any doubts targeting keys presuppositions in the appropriate conversational setting. Le 07/08/2021 à 12:48, Carlos E. R. a écrit :

On 07/08/2021 08.58, Adrien Glauser wrote:

...

Dear Richard,

Thanks for your email. This is utterly offtopic but it's a good point I'll be pleased to talk with you about in private or publicly if you open a Git Issue or a new topic. I will not pursue this topic here.

Why offtopic? This is a matter of interest to any wiki contributor in the past.

How are you going to solve the issue of the licensing, is core to this migration. And as I see it, it is impossible to change the license of the texts, and you are bound to accept it.

People can object to having a page their use or maintain migrated; if they do so, please get in touch with me privately or through GitHub so that I can: 1. verify that they indeed are maintainers of the said page; and 2. negotiate with them; and 3. should (2) not bear fruits, organize a record of untouchable pages. Also if anyone was not clear about this already: - the revamped docs is already using the same license as the wikis - the license does not in any way require to collect individual consents from authors of the wikis, for they have already given their consent as part the license applicable to the wikis; the license merely requires to name five of the principal authors of the contents of the Document (i.e. wikis) - if Richard is interested in helping us in a constructive way, he is kindly invited to send us or send me (off thread) the name of five of the principal authors of the contents of the wikis he thinks should be referenced in the revamped docs. Usually I would simply use the top five contributors from https://en.opensuse.org/Special:Contributions but this tool apparently does not work as of this email. Le 08/08/2021 à 11:27, Richard Brown a écrit :

...

On 8. Aug 2021, at 08:15, Adrien Glauser wrote:

- the topic of this thread is: 'How can I help the volunteers working on the revamped docs deprecating & migrating wiki contents?'

So sticking to the topic.

Did I miss a meeting, thread, or other means of communication where a significant proportion of my fellow wiki contributors were consulted before it was decided to deprecate the current platform and to migrate their content to another platform?

Was the needs of those continual contributors to the wiki considered? Carlos’ and Pers’ posts on this thread would suggest not, but I am certainly open to the idea we all missed something.

It's simple, Richard: - you want to question, contest or otherwise undermine presuppositions that will require to (re) build part of the context behind the initiative and trigger further arguments? awesome! start new topic on the docs ML or on GitHub, so that other volunteers working with me can have their voices heard too (I am not their speakperson outside of the scope of the request at the origin of this thread and they are not subscribed to this ML let alone follow this topic) - you want to help in a way that complies with the request at the origin of the topic? nice, that's the right topic! Have a nice week! Le 08/08/2021 à 12:32, Richard Brown a écrit :

...

On 8. Aug 2021, at 12:09, Adrien Glauser wrote:

 - if Richard is interested in helping us in a constructive way, he is kindly invited to send us or send me (off thread) the name of five of the principal authors of the contents of the wikis he thinks should be referenced in the revamped docs. Usually I would simply use the top five contributors from https://en.opensuse.org/Special:Contributions but this tool apparently does not work as of this email.

A few immediate questions

1. Why should I (or anyone else) be compelled to work constructively with this initiative? As others have already commented, this endeavour seems to be operating with no public explanation as to their goals or the intended benefits to the Project. Without such justification, I’m not even in a position to consider whether I’d even want to help this.

2. Why should this be the decision of just 5 people? The wiki is the authoritative source of huge amounts of our projects work, is contributed to by hundreds and is used by thousands of people. Who are you to say that the top 5 contributors are the only people you’d need to listen to?

I think the change of the projects main documentation platform should be discussed by the whole project (with extra weight given to the existing contributors who’d be impacted by any change). the needs of the whole project should be considered, but so should the existing contributiors be considered if their continued contribution is desired.

3. Why the double standard? You expect folk like me to engage constructively with your efforts when those efforts are clearly destructive to the existing wiki and the contribution accessibility of existing wiki contributors? I think you’d find far more constructive feedback if you weren’t talking about deprecating a heavily used platform and dismissing/ignoring-as-offtopic the questions of the existing users & contributors of that platform.

On 8/8/21 8:17 PM, Adrien Glauser wrote:

It's simple, Richard: - you want to question, contest or otherwise undermine presuppositions that will require to (re) build part of the context behind the initiative and trigger further arguments? awesome! start new topic on the docs ML or on GitHub, so that other volunteers working with me can have their voices heard too (I am not their speakperson outside of the scope of the request at the origin of this thread and they are not subscribed to this ML let alone follow this topic) - you want to help in a way that complies with the request at the origin of the topic? nice, that's the right topic!

Have a nice week!

Given that a large part of this topic is not just limited to docs but also the wiki I believe that this project list is a perfectly reasonable place for such discussions. As the docs team you are more then entitled to take content from the wiki and use it within new docs, how ever without broader project consent you can't remove content from the wiki. While I know you have presented some justification for this at the openSUSE conference not everyone has seen that, the best place for you to present your case for removing content from the wiki and moving to a new docs system is this list (but probably not this thread). Really it is up to the docs team to justify to the rest of the project why they think it is the best way forward and to sell the move. Yes if you don't get broader project consent to remove content from the wiki it will be a bit more work for you but at the end of the day I don't think it has to lead to a significantly worse user experience. After all the docs team is well within its rights to add a link in a banner at the top of any page saying this topic is also covered in the docs with a link to the page. I am sure people also don't have a problem with removing information that is so out of date that it is no longer useful. Or with adding banners that indicate that info on a page is likely out of date and may not be reliable (There has been a number of times where out of date wiki pages have still provided me with useful info on resolving a problem). Beyond that it shouldn't be hard for the docs team to either write a tool or manually watch certain pages for changes and integrate them into the new docs, from the sound of this thread such an approach seems like it would appeal to members of the project that have had a significant history of contributing to our docs. Yes fragmentation isn't always good but if it leads to more contributions from more people maybe it also isn't bad. At the end of the day though the decision around whether we have fragmentation or not here is one for the broader community in this area not just the current docs team, as its the broader community that has spent the last 10+ years putting the wiki together. Cheers -- Simon Lees (Simotek) http://simotek.net Emergency Update Team keybase.io/simotek SUSE Linux Adelaide Australia, UTC+10:30 GPG Fingerprint: 5B87 DB9D 88DC F606 E489 CEC5 0922 C246 02F0 014B

Hi On 8/9/21 10:38 AM, Adrien Glauser wrote:

Hey Simon, thanks for stepping in,

As far as attribution requirements entailed by the current wikis' license, I have turned to SUSE for advice. More out of curiosity and taste for tragic irony than for leverage: Even if there is no concept of collective works in the license, there is little gain to turn the interpretation I think is the one supported by the text against anyone, whether or not it is considered defensible by legal experts.

Common decency to the wikis' contributors goes without saying and I've set up https://en.opensuse.org/openSUSE:Documentation_migration to reference most of the explanations, plans and claims I have made on this issue.

Thanks this will be helpful for some i'm sure.

I worry that the remarkable output of emotional energy in here has obscured that there is no plan to *deprecate the wikis*. There is only a plan to *deprecate some clearly identified portions of the wikis*. More details in the document above.

Yeah in my opinion some of the messaging here hasn't been clear enough and this is an unfortunate side effect.

I'll put forth my plan before the Board next week, and there we will be able to converse at more leisure. The position I will be defending is that removing certain pages -- covering critically important aspects but outdated and factually off -- is the best possible course of action in view of the risk that, during a certain time window, the pages will be picked up by search engines and ranked as high as their superior counterparts offered by the "revamped docs". (If it was only for me I would have edited out these pages, but I feel more comfortable doing once a substitute is available).

Sorry but this isn't the best way forward here, the board can't make any decisions on this topic with exception of two minor points that i'll cover in a minute, we are not a technical decision body. Rather then putting forward your plan to the board you need to put it to the greater community, probably via this list and maybe also an article to news.o.o In my opinion the wiki page you have written and referenced above is a great starting point for this. Then based off the discussion we can see if there is a reasonable consensus among most of the community. Really its only the boards role to act if we end up in a state were wiki pages are being removed by one group and reinstated by another group, (or if this looks likely) then the board will have to come to some form of agreement on how to go forward as it will clearly be a conflict between contributors. The second is if people have concerns around licensing which could clearly become a issue for the board if not done right. Rather then a second email, each page has a history [1] as an example, from here you can get access to a list of authors, common practice in many software projects is to ship one or multiple AUTHORS files that list all the contributors and reference that file in the license header. It would likely be minimal or less effort to create such a file for each page that's migrated in its own namespace. As you mentioned above you are not migrating the whole wiki and there is a large amount of areas such as board info, packaging guidelines etc so if you were to just take the most significant wiki contributors or something like that there is a chance you could end up with a list of people that didn't contribute to any page in question while not listing the people that did Cheers Simon 1. https://en.opensuse.org/index.php?title=Additional_package_repositories&action=history

Le 09/08/2021 à 02:41, Simon Lees a écrit :

...

On 8/8/21 8:17 PM, Adrien Glauser wrote:

...

It's simple, Richard: - you want to question, contest or otherwise undermine presuppositions that will require to (re) build part of the context behind the initiative and trigger further arguments? awesome! start new topic on the docs ML or on GitHub, so that other volunteers working with me can have their voices heard too (I am not their speakperson outside of the scope of the request at the origin of this thread and they are not subscribed to this ML let alone follow this topic) - you want to help in a way that complies with the request at the origin of the topic? nice, that's the right topic!

Have a nice week!

Given that a large part of this topic is not just limited to docs  but also the wiki I believe that this project list is a perfectly reasonable place for such discussions.

As the docs team you are more then entitled to take content from the wiki and use it within new docs, how ever without broader project consent you can't remove content from the wiki.

While I know you have presented some justification for this at the openSUSE conference not everyone has seen that, the best place for you to present your case for removing content from the wiki and moving to a new docs system is this list (but probably not this thread). Really it is up to the docs team to justify to the rest of the project why they think it is the best way forward and to sell the move.

Yes if you don't get broader project consent to remove content from the wiki it will be a bit more work for you but at the end of the day I don't think it has to lead to a significantly worse user experience. After all the docs team is well within its rights to add a link in a banner at the top of any page saying this topic is also covered in the docs with a link to the page. I am sure people also don't have a problem with removing information that is so out of date that it is no longer useful. Or with adding banners that indicate that info on a page is likely out of date and may not be reliable (There has been a number of times where out of date wiki pages have still provided me with useful info on resolving a problem).

Beyond that it shouldn't be hard for the docs team to either write a tool or manually watch certain pages for changes and integrate them into the new docs, from the sound of this thread such an approach seems like it would appeal to members of the project that have had a significant history of contributing to our docs. Yes fragmentation isn't always good but if it leads to more contributions from more people maybe it also isn't bad. At the end of the day though the decision around whether we have fragmentation or not here is one for the broader community in this area not just the current docs team, as its the broader community that has spent the last 10+ years putting the wiki together.

Cheers

-- Simon Lees (Simotek) http://simotek.net Emergency Update Team keybase.io/simotek SUSE Linux Adelaide Australia, UTC+10:30 GPG Fingerprint: 5B87 DB9D 88DC F606 E489 CEC5 0922 C246 02F0 014B

On 8/9/21 4:40 PM, Adrien Glauser wrote:

Hey again,

I think you have read something into my announcement regarding the Board. I am not seeking permission or approval or help from the Board. The only reason for me to put forth the plan there is: - to be transparent (and yes, there will be a post on news-o-o soon) - to allow for the opposition -- if any -- to contest us there, if they so desire - to listen to good pieces of advice of people there *in a dispassionate and a decent atmosphere* because this ML has a tendency to spiral into unrestrained lashes of negative emotion too rapidly for me to be able to pull the nose up before hitting the trees (sorry for all those who have shown appreciation for our initiative and have made constructive criticisms, https://en.opensuse.org/openSUSE:Documentation_migration owes you). In other words, because of this sorry experience I think I will be avoiding non-live communication channels of communication in the future, for I suspect that the vocal minority which is so keen to make accusations and turn to grotesque hyperbolas here would never dare to behave like that in a live setting.

Also I apologize to everyone for whom my original message didn't make it clear enough that the migration was part of a three-pronged plan where care and scrutiny prevailed over carpet-bombing.

That said, I think that there is a belief, ingrained in the mind of a few participants to this ML, that this ML acts in the capacity of a committee or a body of representatives, when in fact subscribers represent no one but themselves. So when I said we wanted to secure broad consent, a few people inferred that we were seeking their consent or approval when in fact the consent and approval we are interested in came in different priorities. (This mistaken inference was spotted earlier by Stefan Seyfried, when he said our initiative was just do-ocracy at play). Primarily, we were interested in the positive opinion of people who: - themselves maintain wiki pages, and - are ready to work in person with us to improve the situation of the documentation platforms for all users.

The more pages one maintains, and the more willing to work one is, the more important one's consent and approval are. The converse is true as well.

Sorry but its for this reason that presenting to the "Board" doesn't make much sense, while some of us do contribute to the wiki we are by no means a large representative sample of the people doing such work, as such while we may be able to offer some advice asking us wont provide a complete picture. Beyond that we are a global community and as such getting everyone interested in a topic into a live meeting at the same time is practical impossible, its almost impossible to find a time that suites the whole board and we know that for significant portions of the community making the board meeting at its current time is impossible but the time is what it is because its the one time in the fortnight that works for all members of the board. I know for a fact that we have wiki contributors from European, US and Asia Pacific timezones as such expecting everyone with interest to attend a live meeting is unrealistic a reality of being a Global project is that we need to live with "non-live" communication methods for discussion and making project wide decisions. It should also be noted that most if not all contributors to this thread have been contributors to the wiki at some point in time. At the same time I think a fresh start for this topic with a clearer description of the WHY which you have now written would be beneficial. That doesn't mean that you need unanimous support of everyone involved in the thread and as always there is the expectation that anyone who participates in the thread abides by our code of conduct. So while yes the board meeting could be a source for feedback it can't be the main source and as you'll find if board members have questions / feedback we are just as likely to provide it via the list. Cheers Simon

...

...

I'll put forth my plan before the Board next week, and there we will be able to converse at more leisure. The position I will be defending is that removing certain pages -- covering critically important aspects but outdated and factually off -- is the best possible course of action in view of the risk that, during a certain time window, the pages will be picked up by search engines and ranked as high as their superior counterparts offered by the "revamped docs". (If it was only for me I would have edited out these pages, but I feel more comfortable doing once a substitute is available).

Sorry but this isn't the best way forward here, the board can't make any decisions on this topic with exception of two minor points that i'll cover in a minute, we are not a technical decision body.

Rather then putting forward your plan to the board you need to put it to the greater community, probably via this list and maybe also an article to news.o.o In my opinion the wiki page you have written and referenced above is a great starting point for this. Then based off the discussion we can see if there is a reasonable consensus among most of the community.

Really its only the boards role to act if we end up in a state were wiki pages are being removed by one group and reinstated by another group, (or if this looks likely) then the board will have to come to some form of agreement on how to go forward as it will clearly be a conflict between contributors.

The second is if people have concerns around licensing which could clearly become a issue for the board if not done right.

Rather then a second email, each page has a history [1] as an example, from here you can get access to a list of authors, common practice in many software projects is to ship one or multiple AUTHORS files that list all the contributors and reference that file in the license header. It would likely be minimal or less effort to create such a file for each page that's migrated in its own namespace. As you mentioned above you are not migrating the whole wiki and there is a large amount of areas such as board info, packaging guidelines etc so if you were to just take the most significant wiki contributors or something like that there is a chance you could end up with a list of people that didn't contribute to any page in question while not listing the people that did

Cheers

Simon

1. https://en.opensuse.org/index.php?title=Additional_package_repositories&action=history

...

Le 09/08/2021 à 02:41, Simon Lees a écrit :

...

On 8/8/21 8:17 PM, Adrien Glauser wrote:

...

It's simple, Richard: - you want to question, contest or otherwise undermine presuppositions that will require to (re) build part of the context behind the initiative and trigger further arguments? awesome! start new topic on the docs ML or on GitHub, so that other volunteers working with me can have their voices heard too (I am not their speakperson outside of the scope of the request at the origin of this thread and they are not subscribed to this ML let alone follow this topic) - you want to help in a way that complies with the request at the origin of the topic? nice, that's the right topic!

Have a nice week!

Given that a large part of this topic is not just limited to docs  but also the wiki I believe that this project list is a perfectly reasonable place for such discussions.

As the docs team you are more then entitled to take content from the wiki and use it within new docs, how ever without broader project consent you can't remove content from the wiki.

While I know you have presented some justification for this at the openSUSE conference not everyone has seen that, the best place for you to present your case for removing content from the wiki and moving to a new docs system is this list (but probably not this thread). Really it is up to the docs team to justify to the rest of the project why they think it is the best way forward and to sell the move.

Yes if you don't get broader project consent to remove content from the wiki it will be a bit more work for you but at the end of the day I don't think it has to lead to a significantly worse user experience. After all the docs team is well within its rights to add a link in a banner at the top of any page saying this topic is also covered in the docs with a link to the page. I am sure people also don't have a problem with removing information that is so out of date that it is no longer useful. Or with adding banners that indicate that info on a page is likely out of date and may not be reliable (There has been a number of times where out of date wiki pages have still provided me with useful info on resolving a problem).

Beyond that it shouldn't be hard for the docs team to either write a tool or manually watch certain pages for changes and integrate them into the new docs, from the sound of this thread such an approach seems like it would appeal to members of the project that have had a significant history of contributing to our docs. Yes fragmentation isn't always good but if it leads to more contributions from more people maybe it also isn't bad. At the end of the day though the decision around whether we have fragmentation or not here is one for the broader community in this area not just the current docs team, as its the broader community that has spent the last 10+ years putting the wiki together.

Cheers

-- Simon Lees (Simotek) http://simotek.net Emergency Update Team keybase.io/simotek SUSE Linux Adelaide Australia, UTC+10:30 GPG Fingerprint: 5B87 DB9D 88DC F606 E489 CEC5 0922 C246 02F0 014B

On Mon, 2021-08-09 at 10:28 +0200, Adrien Glauser wrote:

workable feedback. That's the rest of the "big picture" I am interested in as far as feedback. (Feedback from this ML has been duly noted already, thank you for that.)

the capacity of some to show restraint in an offline setting, to propose a live alternative. There is ample evidence that live settings are helpful when emotions run high.

Furthermore, the Board meetings are the best possible place to prevent and mitigate tensions -- it's even part of their mandate -- and I don't know about you, but I feel there is tension aplenty.

This is why *I am thereby proposing any one from the opposition to meet us*. That's one great opportunity! And if instead they prefer to meet in the Bar at any another time, just let us know, we can certainly arrange something at a time that suits their agenda. :)

See you next week!

https://en.opensuse.org/openSUSE:Guiding_principles "We value transparency of the decision making processes, transparency of communication and transparency of work and collaboration processes. That includes openly answering questions, providing all relevant information, and actively keeping all involved parties informed. We are convinced that a transparent culture whose inner workings can be understood by everybody provides the most efficient and rewarding environment to reach our goals." I do not feel that limiting all discussions on this topic to in person meetings is consistant with the above core value of the openSUSE Project. The Project is larger than the few people who have the time/timezone to be able to attend in person meetings. Excluding/disenfranchising those who cannot attend those meetings actually undermines the intended function of those meetings (to provide an additional venue for discussion, not an exclusive one). The Board meetings are not to be used as to form exclusive cliques that undermine the work of contributors in the wider communities. So, I echo everything else Simon already said on this topic. His good advice on how to proceed is out there, openly, transparently. I suggest you follow it.