Make a new category in Ask, right below Start Here, to enhance visibility (e.g. “Guides”).
Create a short guideline on how a guide should be constructed: layout, tools to use, depth of the subject etc. Pin the guideline in the “Guide” category.
Create a few tags that are dedicated to guides, more as to give a sense of navigation through the topics, given that there is no possibility for Table of Contents (such as in the Quick Docs). Most of them might be there already.
Consider creating all guides as wikis (with all the pros and cons that someone else can edit the post/wiki). The guides have to be up-to-date, and this can be ensured if it can be done by other contributors too.
All topics created in the “Guide” category should have the default setup of replies getting automatically deleted after one week (or similar). Readers would loose focus if there are lots of replies to the Guides. The one week timeframe would work out for example if someone wants to inform the creators/maintainers of the guide that parts of it became outdated.
Divide (how?) the guides into 2 categories: general (applicable to any user, e.g. How to System Upgrade), which would resemble Quick Docs, and specific (applicable only to certain users, e.g. regarding specific drivers, software etc).
Limit the creation of topics in the “Guides” category to certain users (be it TL level, a specific user group etc).
Link guides in other posts, when applicable.
Spread the word in the forum to those candidates who would be suitable and willing to start working on the guides in the new category.
I can imagine, though, how some of these ideas might be considered applicable rather within a more organized entity, than a forum.
IMO there is a big point to consider in HOWTOs and guides: the review before publication.
I can write a guide full of errors or misleading commands, still they are promptly and publicly published here on the forum.
But. If I publish a wrong guide on my blog, the only person to blame is the blog owner (me). If I publish an howto that doesn’t work (or worst) here on this forum, the reader will probably blame Fedora and not the author.
I can agree that the docs/quick-docs workflow is a bit hard. I can agree that it is difficult to contribute, especially for people that simply want to add a single howto or a guide. But I think that this is an issue that should be officially solved by some Fedora leadership and governance body. I think that starting a new Category here and/or allowing/encouraging people to freely publish their guides here without any coordination or standard procedures, it might lead to some problems.
This could be solved by creating a subcategory Staging (or similar) within the HowTos/Guides category, with only limited access (such as the limitation in place for Moderator Coordination subcategory). After a certain review period, based on some rules, either the author, or maybe a member of the (newly created) Guide Reviewers team, would move it to the final location, which has full visibility.
One caveat would be that the creation and review of how-tos would be limited to a certain group of people (but this can be seen as an advantage too).
If we did this, I’d suggest we enable the Discourse Docs plugin. (It’s already installed, just not turned on.)
Right, that’s the other thing. I think that if we decide to do this, it should be along with retiring Quick Docs entirely. Or, in fact, making this the “Quick Docs”. But I’d like buy-in (or at least acceptance!) from the docs team for that. I don’t want to end up splitting effort, attention, and search results.
For what it’s worth, from the Google Search Console, the overall docs.fedoraproject.org site got 2.57M click-throughs in the last 12 months, with a click-through ratio of 5.2%. Of that, more than half (1.40M) led to something under quick-docs — although the click-through ratio is only 3.7%.
Because the category doesn’t go in the URL on Discourse, I can’t, do that same breakdown, but the site overall got 3.68M clicks, with a CTR of 4.1%. From a scan of the top 100 entries, it seems overwhelmingly to be Ask-type searches (“fedora update grub”, “nvidia kernel module missing falling back to nouveau”, etc.).
Here is the article published in the Fedora Magazine. It is about what Fedora Docs is proposing by taking Ask Fedora responses and turning them into a knowledge base!
In my opinion, it might be too early for such a decision. At its early beginnings, these Guides would be some sort of trial project, which has yet to prove itself as a potential successor of Quick Docs. Running them in parallel (for a while at least) could be beneficial, also because the Guides project could then follow its own development path. Among others, the guides should be quicker to write than Quick Docs (pun intended), with all the pros and cons that derive from such an approach.
Once mature, the Guides project could either become the new Quick Docs, or it might fail in that pursuit, and just remain a supporting tool for the helpers active in Ask Fedora.
You mean fresh signed up long time Fedora members where used mailing list instead of discourse as an example? That they do miss the TL3 of above status to help review?
We could add a system for old contributors to request some status like TL3. I think it may be problematic that the levels below TL4 will revert back on inactivity.
As I see the situation we do have now would give some kind of issues. Maybe a staging discourse instance where we do have access with a fedora group membership. We could copy the howto & guide tagged articles there and try with the doc module @mattdm mentioned. There we would not have to make it in a hidden category the review.
Would this be an idea?
And of course moderated with someone who takes the lead and says … so we try/do it.
A vast number of knowledge accumulated in Ask Fedora is huge and fast. However, solutions in Ask Fedora have its own place and are not intended to replace Quick Docs by popularity and outcome of A/B testing.
There are countless hours put into the state of Docs and months of making tutorials for a broader audience. Quick Docs is one of them.
have a proposal system, automatic or manual poll, after 2 weeks or so it gets moved to the howto category
See how it evolves
Think about replacing the QuickDocs
I think the main advantage here is the integration with issues, quick referencing, better accessibility and approachability. But currently it is a bit of a mess and we dont have a scope.
