@ankursinha Somewhat related, this was the inspiration for fedora-commops#159. However, I don't have bandwidth to drive that effort any longer. If someone was willing to put in volunteer time to organize a community docs virtual hackfest, I'm in a better position to play a supporting role than a leading role on this.

+1, I get that. I wish I had the bandwidth to organise this too. I guess we can write a commblog etc to try and get more folks involved to begin with (as low effort requiring tasks)?

But, in the absence of such a review, I do not believe the quick-docs are ready for consumption by end-users. There are far too many documents that were exported from outdated wiki pages, and instead of helping users with common issues, the quick-docs in their current state are more likely to cause issues.

It may sound a little extreme, but IMO untill these docs have been reviewed, quick-docs should be removed from docs.fp.o. Unlike software where we can release alphas/betas to the public, I do not think we can do the same for documentation, especially if it's meant for end-users.

By the way, who is in-charge of quick-docs? Is it comm-ops or is it the docs team or is there a different SIG? Who looks after these? If no one does, they're just the same as wiki pages in a new location (that looks more official and is therefore more dangerous since users will trust them more): they'll be outdated, they'll contain incorrect information.

+1, I get that. I wish I had the bandwidth to organise this too. I guess we can write a commblog etc to try and get more folks involved to begin with (as low effort requiring tasks)?

A Community Blog post is a good first step. Once a week, there is an existing docs-writing office hours, but I'm not sure if it is active meets. If it does, the office hours could be promoted as a chance to get help or guidance on improving Fedora documentation.

But, in the absence of such a review, I do not believe the quick-docs are ready for consumption by end-users. There are far too many documents that were exported from outdated wiki pages, and instead of helping users with common issues, the quick-docs in their current state are more likely to cause issues.

I understand this point. I disagree dropping quick-docs from publishing is the right solution though.

In the wiki, I might find a page last edited in 2011. Here, I notice a consistent stream of quick-docs improvements from new contributors outside of the core Docs Team. For how this documentation is maintained today, I think it is better to keep them published and solicit contributions and improvements with a clear pathway for doing so.

Additionally, these URLs are public for a while and I am unsure how much traffic the existing docs get from hyperlinking. If these analytics are available, it would be helpful to use them as a data point here. cc: @asamalik @mattdm

It may sound a little extreme, but IMO untill these docs have been reviewed, quick-docs should be removed from docs.fp.o. Unlike software where we can release alphas/betas to the public, I do not think we can do the same for documentation, especially if it's meant for end-users.

I feel like this is the intended role of the published, versioned user documentation: https://docs.fedoraproject.org/en-US/fedora/f29/

I do not see the goal of quick docs to be an authoritative source of absolute information since it they are not attached to Fedora versions. For end users, I see quick-docs as a broad "miscellaneous" category of documentation that doesn't belong in the versioned Fedora User Documentation. Sometimes it may be current or it may be out-of-date, but I don't see this being significantly different from the wiki.

By the way, who is in-charge of quick-docs? Is it comm-ops or is it the docs team or is there a different SIG? Who looks after these? If no one does, they're just the same as wiki pages in a new location (that looks more official and is therefore more dangerous since users will trust them more): they'll be outdated, they'll contain incorrect information.

The Docs Team is responsible, but I don't think there is a "lead maintainer" of quick-docs. I think the folks whose paid responsibilities include Fedora Documentation work on quick-docs when time allows them to. But this is more of a maintenance mindset. I am not sure if there is a fixed goal or purpose for what the quick-docs are. I think spelling out definite goals / anti-goals of quick-docs is helpful, for readers, writers, and maintainers.

I agree on most points, but not on the point that quick-docs are similar to wiki pages. As I understand it, if they are on docs.fp.o, an end user trusts them. This was not the case on the wiki---pages there do not appear to be official documentation and one does not get that impression there.

If quick docs are similar to wiki pages, there's no point to them in my book. Editing wiki pages is much easier. Quick docs just adds more work then by enforcing a PR system for contribution. So, they must be better than wiki pages. (It does not matter if they are version agnostic, that does not make them similar to wiki pages)

The current issue is only because the automatically exported wiki pages have not been reviewed---they did not go through the PR process. New contributions do go through the PR process and are therefore reviewed.

Could we mark the auto-exported pages as "automatically exported, unreviewed" maybe if we're not taking them down? All I really want is for end-users to be aware that some of the information on quick-docs is not 100% trustworthy.

Requested review on commblog post draft: https://discussion.fedoraproject.org/t/article-for-review-contribution-opportunity-quick-docs/1303

@ankursinha Thanks for making the blogpost.

Quick-docs are similar to wiki pages in that most of them are literally converted wiki pages. Some time ago a decision was made to move this kind of content from the Wiki to docs.fp.o. Quick-docs are the top 50 (IIRC) accessed Wiki pages, converted to ASCIIDoc and published with Antora.

The exported Wiki pages have mostly only been cleaned up (the automatic conversion to ASCIIDoc wasn't very accurate). I'd love to have someone review them from a technical standpoint, but it would need a distributed effort; there's some stuff in there that would require specific hardware to test (the Bumblebee doc comes to mind), and even with pages that don't require any specific equipment, you still need someone with knowledge in the area.

I see your point about marking auto-exported and unreviewed pages. I'll do that this week, there'll be a banner on top of each page explaining the situation. Can you please edit the blogpost, and tell people who want to review an existing quick docs for accuracy that:

• If they review a doc and find problems, then they should either open a PR fixing them (preferred), or at least open an issue describing the problems and how to fix them; I'll try to fix it when I can. (If anyone makes a PR they should also remove the "unreviewed" banner that I'll be adding; it's going to be inserted as an include:: statement near the top of the top-level file)

• If they review a doc and don't find any problems, they should either open a PR stating that it's fine (and, again, removing the banner), or at least open an issue telling us it's fine and I'll remove it myself

We'll use the banners to show us which docs have been reviewed and which haven't. What do you think?

@ankursinha Thanks for making the blogpost.
Quick-docs are similar to wiki pages in that most of them are literally converted wiki pages. Some time ago a decision was made to move this kind of content from the Wiki to docs.fp.o. Quick-docs are the top 50 (IIRC) accessed Wiki pages, converted to ASCIIDoc and published with Antora.

So, I understood this differently. In my head, quick docs are not wiki pages: wiki pages are scratch pads for anyone to write anything. They are mostly unvetted. Quick docs, on the other hand are documentation so must be vetted. My understanding was (is) that a "popular" set of wiki pages were auto-exported to seed/initialise quick docs until they got off the ground and started receiving community contributions.

The exported Wiki pages have mostly only been cleaned up (the automatic conversion to ASCIIDoc wasn't very accurate). I'd love to have someone review them from a technical standpoint, but it would need a distributed effort; there's some stuff in there that would require specific hardware to test (the Bumblebee doc comes to mind), and even with pages that don't require any specific equipment, you still need someone with knowledge in the area.
I see your point about marking auto-exported and unreviewed pages. I'll do that this week, there'll be a banner on top of each page explaining the situation. Can you please edit the blogpost, and tell people who want to review an existing quick docs for accuracy that:

If they review a doc and find problems, then they should either open a PR fixing them (preferred), or at least open an issue describing the problems and how to fix them; I'll try to fix it when I can. (If anyone makes a PR they should also remove the "unreviewed" banner that I'll be adding; it's going to be inserted as an include:: statement near the top of the top-level file)

If they review a doc and don't find any problems, they should either open a PR stating that it's fine (and, again, removing the banner), or at least open an issue telling us it's fine and I'll remove it myself

We'll use the banners to show us which docs have been reviewed and which haven't. What do you think?

Sounds good (similar to the "needs love" banner that we had on the wiki at some point?). Unfortunately, the post has already been scheduled so I cannot edit it anymore. Would it make sense to have a CONTRIBUTING.md file here in the quick-docs repo instead?

So, I understood this differently. In my head, quick docs are not wiki pages: wiki pages are scratch pads for anyone to write anything. They are mostly unvetted. Quick docs, on the other hand are documentation so must be vetted. My understanding was (is) that a "popular" set of wiki pages were auto-exported to seed/initialise quick docs until they got off the ground and started receiving community contributions.

Well, yes. The point of the migration was to separate the "scratchpad" from user docs that people were writing on the wiki instead of here. You're basically right, I'm just saying that "improving the quality" wasn't the primary goal, although I see your point that something being hosted on docs.fp.o instead of the wiki makes it seem more authoritative so we should strive to be more correct. I hope your blogpost helps fix that :)

Sounds good (similar to the "needs love" banner that we had on the wiki at some point?). Unfortunately, the post has already been scheduled so I cannot edit it anymore. Would it make sense to have a CONTRIBUTING.md file here in the quick-docs repo instead?

Ah, okay, I'll add a CONTRIBUTING file then. Now that I think of it, it wouldn't hurt to have one for each docs repo. Hmmm.

Okay, I didn't add a CONTRIBUTING since the README already had some contributing instructions - and it shows up by default if you open the repo on the web so the info is better visible there.

I added info for reviewers to the README and each top level page now has a banner stating it could use a review.

It's been a year since the last comment on this ticket. I think the great work @hhlp has done recently in opening new issues for many specific pages is sufficient to close this as "complete." I think driving incoming folks to jump on an issue for a specific page at a time is a good approach.

I'm closing this issue as complete, but @pbokoc @ankursinha, feel free to reopen if you think there is more discussion to be had here.