openSUSE:Documentation migration

Warning: Wiki pages are not currently being moved to the revamped docs, as decided in the community meeting at December 21st, 2021 (https://etherpad.opensuse.org/p/weeklymeeting20211221)

Disclaimer

This page expresses the views of the maintainers of the "revamped" documentation. It does not express any official view nor is it a manual. Please be considerate and refrain from editing. Use the Discussion section if you must.

Intro

The migration is the process of flagging, copying content from and, in certain circumstances, removing pages from these wikis for the benefit of quality assurance, durability and organizational efficiency.

This process has limited scope: it concerns only Tumbleweed-only contents and key overlaps between Leap and Tumbleweed. It is not enforced upon anyone. Anyone not interested in having a page their maintain migrated can opt-out at any moment.

Moving to a revision control-based maintenance model for documentation is nothing original is regarded as best-practice by many reputable Linux distributions:

... as well as an excellent distribution some of us might have heard of.

Of course wikis have a role to play in tech communities. Ubuntu's wiki summarizes this role well: Howto's, tips, tricks and hacks. But when tips become best-practice, they deserve a more stable home than Wikis can provide, even more so when there is nothing else than these "tips" as documentation for Tumbleweed.

What is the rationale behind the migration?

The rationale behind the migration has been explained in more details here.

In a nutshell, the idea is to copy and/or remove some pages of these wikis because:

wikis are "unsafe" documentation platforms in the sense that a new user cannot distinguish between factually adequate, up-to-date and best-practice-compliant contents from contents that lack any of these three features
this problem is multiplied by the ratio quantity of up-to-date contents sufficient to cover all areas useful to a new user / quantity of available contributors over time, which means that if you have a lot of contents to cover and few people to maintain it over time, as is the case on these wikis, the contents will lose quality over time
new users are obviously aware of these shortcomings, and thus have to live with the uncertainty that the particular piece of information or advice they have found might be flawed
the effects of outdated / factually incorrect contents (i.e. search engine highly ranked results) is mitigated after we have migrated or flagged or removed them, and finally:
an identifiable and accountable team of people (for now, the contributors at https://github.com/openSUSE/openSUSE-docs-revamped-temp) acting in concert can organize peer-reviewing and carry out the other important parts of the QA process, leading to a potentially more consistent documentation, compliant with best-practices and where all parts of the documentation share the same fate

What parts of the wiki are relevant to the migration?

The migration is for now (August 2021) focused on the flagging season (see the section below for the full plan).

Relevant are contents which:

apply to Tumbleweed or to key overlaps between Tumbleweed and Leap documentation (see our table of contents for the full list: https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/ToC.md, deployed at https://opensuse.github.io/openSUSE-docs-revamped-temp/index.html); or
fall within a topic important to new / average users.

The rest of the wikis, the hacks, tips and tricks are not the least affected by this initiate. Wikis are excellent tools for coordinating teams and community activities, and nothing we have said so far undermine this.

Important

Notice that this notion of relevance generates the following possibilities:

1. page W on the wikis is relevant in the sense above and has a counterpart in the revamped docs which is:

a. clearly better (more complete, detailed, or better presented)
b. equally good
c. clearly worse (either less complete or less detailed or not better presented)

2. page W on the wikis is relevant in the sense above and has no counterpart in the revamped docs, and:

a. has good quality
b. does not have good quality.

These possibilities generate different courses of action:

2a: (migrated notice + redundancy flag if the wiki is not well-maintained) the page is copied as is, with the adequate links so that both the original and the copy reference each other, and the attribution to the original page is explicit
2b: (migrated notice + removal flag) what can be copied is, a reference to the copy is made, and the page on the wikis is flagged for removal
1c: (deprecated notice + removal flag) the page is flagged for removal, with adequate links to the better counterpart in the new docs
1a,b: (mirrored notice + redundancy flag if the wiki page is not well-maintained) the page is flagged as having a better/equal counterpart, with a warning that the counterpart may 'decay' slower as it will get maintainance.

How is the migration planned to unfold?

1. Flagging season

The relevant pages (see the previous section for a definition of "relevant" used here) are flagged as recommended (see the next section for details).

2. Negotiation and opposition season

Wiki contributors with flagged pages are invited to get in touch with us if they want to accompany the migration of the page(s) they maintain.
Wiki contributors who oppose the migration of their page(s) are also invited to say so. We will be negotiating with them to seek a workable solution.

3. Resolution season

All flagged pages are 'resolved': copied and either edited out or exempted as per an opposing maintainer or better left behind for some other reason.

Legend

Notices

mirrored: the wiki page has a counterpart that was not necessarily copied from it, and both pages are about equal in terms of quality, presentation and coverage.
migrated: the wiki page has been copied into the new docs
deprecated: there is nothing to take from the page even though the page is relevant according to our use of "relevant".

Flags

redundancy flag: the page might intercept users who might be better served by a counterpart of this page in the new docs, as only the latter is guaranteed to be maintained.
deprecated: the page should be terminated.

3. Add the URL of the page you just flagged to the list in the first section of this document.

4. If you want to help us even more and actively help us migrate the pages you've just flagged, please get in touch!

A wholehearted THANK YOU for your help at improving the user experience of future users!

More questions

Brief comparison between the source control-based vs. the wiki-based contribution models

The main premise fueling this initiative is that the source control-based contribution model are advocating is more beneficial for the community now and in the long run than its current wiki-based counterpart. In this context:

source control platform stands for GitHub and very soon openSUSE's Pagure instance
public channels stands for our mailing list and Pagure and/or a web service we might design for the purpose of lowering the entry barrier for new contributors.

Caption: contributions models
platforms	wiki	source control platform
reporting a document for changes/deprecation	set a flag and wait until someone notices it	open an Issue which automatically notifies maintainers
discussing past or future changes to a document	make a speech on the mailings, write lines to the Discussion section and wait until someone replies	open an Issue which will be triaged and assigned to contributors knowledgeable in the topic
editing/writing a document	write wiki syntax, make sure that your connection does not drop when pushing the send button, and hope that people will like your personal style and conventions	write markdown syntax, post the document to any of the public channels; or fork the repo and submit a Pull Request, and then have your text reviewed for language and contents and normalized with other contributors
working offline on documents	you can work on just the documents you manually copy-paste to a file, hoping that the syntax won't get messed up during the copy-paste	you can work on the entire documentation offline after forking and cloning it (which means that you are using a local copy of the documentation which can be synced up to the origin)
introduce a global change	manually edit every page in the scope of the change (~5 clicks per wiki page) unless the change occurs in a template	use the Replace In Files feature of your text editor (~ 2-3 clicks no matter the number of documents)
obtaining peer-review on a document or on submitted changed	send messages over the mailing list you, hope that some subscriber will notice and be available to help you in the next days or weeks	let the maintainers organize the peer-reviewing for you
coordination between several contributors and common consent	N/A	work hand-in-hand with the maintainers to resolve conflicts and iron-out integration bumps
knowledge transfer between contributors and from maintainers to contributors	N/A	simply request maintainership and work hand-in-hand with the maintainers to learn the ropes so that no savoir-faire is left behind over time, even when contributors and maintainers come and go
maintenance routines	as many routines as there are contributors, implemented when they so please	onboarding routines + handling Issues routines + monitoring routines for spotting missing, outdated or incorrect documents

When did this migration idea start?

The idea was originally to just report outdated or erroneous contents in January 2021:

But it quickly appeared that search engines would not stop indexing outdated or erroneous contents until we act a bit more vigorously. Hence the idea of offering a more encompassing approach, of course with the opt-out solution mentioned above.

How will I be able to contribute to the new docs after the migration?

You will be able to:

open Pull Requests or Issues on either GitHub or the openSUSE's Pagure instance hosting our docs (the latter of which will re-use your openSUSE login credentials)
submit modifications directly as markdown files either to your mailing list (see below, Get in touch) or via a web service we will have ready for you in due time.

Every submission will be peered-reviewed at some point, and not just by the maintainers. This alone can ensure that only contents which are tested, up-to-date, and factually correct.

Aren't you making it more difficult for the the community to contribute to the docs?

Markdown is just as simple as the wiki syntax and submitting additions or modifications will be as simple as sending a document via email or via a web. The only significant difference is that modifications will be submitted, not enforced, upon the community. The peer-reviewing process means that new users won't need to be lucky to dodge outdated, untested, incorrect or poorly worded contents.

Documentation maintenance will move closer to a code maintenance contribution model, as is done already by other Linux distributions (see the list in the introduction). And if you suspect that your submissions are being blocked for no good reason, you will be able to use just the same reporting instruments as you can now for anything in openSUSE.

As for maintainers: they are just volunteers like you, and you yourself can become a maintainer by simply requesting it. The only requirement is that it you commit to maintenance.

Isn't it necessary to secure consent from all authors, editors and maintainers of a page?

It is and it is done. Contributors to the wikis already consented when they contributed to the wikis as per the wiki's license.

Moreover, out of respect for the work of contributors, we would like to secure as broad a consent as possible. Thus if you are a contributor to the wikis, maintain relevant pages as per the definition above, and would like to accompany or opt out of the migration of your page(s), please get in touch.

It goes without saying that all contents extracted from the wikis will be attributed.

Are the current 'revamped docs' fully compliant with the wikis' license?

They will be as soon as we are able to reference the authors of contents we take from the wikis. This will be done during the Resolution season (see above).

If you can think of more intellectual property issues, please get in touch.