Standardizing a process and determinants to tackle obsolete and dangerous Docs pages

This topic refers to @pboy 's suggestion from a recent decision we agreed on:

I suggest to discuss a standardized process and determinants to manage such pages:

What to do when we become aware of obsolete or dangerous pages?

Additionally, how to determine if and when a page is obsolete or dangerous? What characteristics/properties to deploy for determining that? When to keep it online and when to put it offline?

Maybe also: easier ways to report that for users (this might be linked to the general topic to increase external contribution I talked about with @hankuoffroad and where we wanted to create a dedicated topic to discuss).

I just ended up myself here: Working with the GRUB 2 Boot Loader :: Fedora Docs

This page dates back to Fedora 21 (!), but its content is not just confusing for users, it can be dangerous: if a user does not recognize that this page does not relate to current Fedoras, the page might cause users to break their system: if you implement things from that page, it may cause a system to no longer boot at all. I know its a worst case outcome, but I think we should care: it’s still a possible outcome of that page. I think this page has been already a topic in earlier ask.fedora threads.

In the past, we tended to wait very long, or wait until the feedback became “very distinct”. But does it make sense to always wait so long before becoming active?

A slight supplement to consider: be aware that once users start to be affected or annoyed by such pages (may it be with or without providing explicit feedback), it can be questioned if this creates incentives for them to contribute.

Please find the meeting topic here - Tackle obsolete pages.

is ‘dangerous’ in the sense of the system made not bootable or something?

Top three questions in Ask and top criteria submitted as issue are;

  • Installation and bootloader
  • Media support (graphic cards, drivers)
  • Upgrade failure

We could prioritize article review cycle. Process and ideas need to be backed up by people (reviewers and writers).

Yes, if a user implements parts of the boot configuration of Fedora 21, this is no longer compatible. So it can lead the system to no longer boot, maybe also break grub (including all installed operating systems). I expect most is reversible, but it needs experience/knowledge to solve such an issue once created (in ask fedora we are limited to the perspective of the users: what the users tell and provide us, and what they are able to provide, and what they are able to implement). Issues like that can be problematic for and with less-experienced users. Grub and boot loader configurations are serious issues where precision is necessary. Also, such issues always need a user to have a second computer.

There is already the editor’s note in the top, which mentions that the page is deprecated and suggests to use instead the page on the Quick Docs, which is less problematic. The note contains the related link. But often people go directly to the part they found with their search engine, use STRG+F, or skim to what seems relevant based upon their problem, and do not read everything else → if any user ends up with one of the section links, they will not see the editor’s note in the top at all.

I think removing the page content and only leave the forwarding makes sense, doesn’t it? Or remove the page, or directly forward to the Quick Docs page? However, I guess at least the latter could be confusing.

Good topic! Indeed, that could indirectly solve several of such issues. This would imply to resolve the two grub pages into leaving only the “better” one from Quick Docs. The other questions (if/how/where forwarding, etc.) of above would be obsoleted as well if the structures of the different Docs would be merged.

I guess we need a pragmatic way to decide about it. If following a guide results in a non-booting system, we should remove that guide. If a guide is older as F30 / 4 - 5 years, we should include am expli.cit warning.

And than we should start to check the most active articles first. We should try to find a reviewer instead of trying to fix every document ourselfes.

100% to your points. But the standardization suggestion is also referring to how to implement the goal. E.g., this situation: I just found this page (or someone made me aware of it) where I can say some contained things can break the system: open a ticket? put it to the meeting? Shall I immediately set it offline when it can break the system?

Usually, a few days more or less make no difference given that these pages are usually online for a long time. So I suggest to not rush.

Given our informal practices, my suggestion would be to open a ticket with the flag “approval needed”, mention it in the next meeting’s topic/thread to make aware (no meeting flag or dedicated discussion during the meeting necessary unless someone wants to), and if one other team member has approved it, set it offline. Does that make sense? That does not impose changes or so, and ensures that two people check before something is deleted. But there are alternatives of course as well.

When the “finder” only intends to add the explicit warning (and no removal of the page), I think we can do the same but replace the explicit second approval with a lazy approval after 2 or 3 days after the respective meeting.

When users create related tickets I would treat these tickets the same way.

100% agreed. Setting an article offline is a pretty tough measure. We should make sure that not 2 arbitrary people can run this process. But at least one should be a regular and continuous participant of docs team discussions/work, or maybe a board member. I would prefer the former. Practically, that would be you, Hank and me at the moment,

And, by the way, I think we need a kind of register of our decisions and regulations. Maybe a dedicated page in our team pages.

1 Like

See the Council Policies section of the Council docs for example.

Could you provide some detailed information? I found this: Fedora Team Directory :: Fedora Docs

By the way, I consider that as very important, but we may have a good way to walk to achieve that, don’t we?

Agreed to all your points. But I think this is a default: only regulars/permanent members have the privileges to remove pages. So a non-regular/non-permament member can only act as the approving second one. I think beyond Hank, you and me, these privileges are only given to darknao, pbokoc and Ben Cotton, and the administrative people that do not intervene in Docs anyway. But you are right that when me formalize this we should make this explicit to avoid confusion.

+1 !

Practically, you are right. Nevertheless, to make it clear (and to provide an - at least implicit - justification) I think it is good to sate it explicitly. And sometimes the assigned privileges and the real situation get out of sync

That makes sense, +1 :wink: