There are many guides like these which are helpful for a lot of people:
But at the same time there’s very little opportunity to show them to our users. There’s the howto tag, which is great, but I guess almost nobody knows about it, especially newcomers. And just plain forum search will not prioritize guides/howtos before regular questions, so people are not very likely to find the top useful stuff.
I wonder if we can make such guides more visible somehow? Perhaps an Ask Fedora subcategory dedicated to guides/howtos would help? Or somehow make even newcomers aware of the howto tag?
I come across such guides frequently in Proposed Common Issues , when people want to make it easier to find to forum readers. It doesn’t fit into Common Issues however, so I move them to Ask Fedora. But I feel there could be a better way. Thoughts?
An issue also is that especially I have made some of such posts that are not Fedora-only.
For example the ADB fix where using official Google binaries was the solution as Fedoras are somehow broken.
I would put them in the Common Issues Category and maybe a subcategory “HowTos”. I see the category is pretty full already.
But are “Issues” just bugs? A discussion forum is more suited to have problems as issues, with a howto to fix them. Putting bugs there may reduce duplicate bugzilla bugs but not really help anyone.
In Common Issues we document problems which are encountered by a large part of our userbase or are very severe. They are mostly bugs, but sometimes they are notable changes which might surprise many users (example). “Broken adb” would not qualify, but “broken Firefox on a raspberry pi” would (and “no graphical output on all intel cards with the latest kernel” definitely would). The point is definitely not to reduce duplicate bugzilla bugs, it is to help people find solutions or workarounds for the most pressing issues.
I don’t want to extend the scope (with general guides on e.g. how to install multimedia codecs), because that would make the category too populated and harder to search for and find the exact issue you’re having. We have to keep the common issues list short, only limit it to the most important problems, otherwise it stops being useful. Also, mixing bugs and howtos is not a good idea.
But an easy-to-find list of howtos is definitely a good idea, in my eyes. We already have many of them in Fedora Quick Docs, but I understand that a lot of our users feel more comfortable writing the guide as a forum post, rather than submitting it as a quick doc. Also I find the Fedora Docs UI somewhat cumbersome to use.
Yeah, I think it’s a good system if you’re already in the docs workflow, but if you’re not familiar, it’s a barrier. At the time, we were expecting Pagure to grow more features which would make it easier, but that’s not how it turned out. I think if we’d had Discourse at the time, I would have located Quick Docs here. (There is a Docs Plugin which we have not activated…) But this is getting into something for docs-team — I’d hate for there to be two confusingly-similar sets of Quick Docs.
Hmmm, actually — despite the name, with a few tweaks, it might be useful to turn that plugin on for all of Ask Fedora. I’ll experiment with that on the staging site…
The issue with the Quick Docs becomes maintenance and expectations.
Maintenance, because we have Quick Docs that are now out of scope with current releases.
Expectations, because the trend of the Quick Docs has changed and for many Quick Docs has become small historical post on a topic.
A Quick Doc should be a How-To, a way to quickly get answers to simple questions. Most of the Quick Docs belong in proper Fedora Documentation while other are lacking in updates or are no longer relevant due to the update process.
I have been attempting to get traction on this for about a month, but I think there needs to be some activity behind the curtain. My goal is to get these Quick Docs translated as well ! but looking through them, they need to be updated, and realigned with other Documentation before translating them.
I think the Docs need more community involvement, more active contributors.
This is a reason why I have not launched some of the Docs I have written ( in 3 languages. . . ) already. Because we have the solution. Just the other day I used my personal Docs here on the forum to troubleshoot an issue with a non English speaker :
This should be a Quick Doc on the Fedora Docs page but the English version would not be compatible, as it is overwhelming for a Layman/New User (or new user looking for a quick solution) which can be tense moments.
In terms of searchability/findability of solutions, my experience tells me the opposite. I get good search result from on-site full text search (An Antora extension) in the Docs site.
Just curious what aspect of Docs UI is cumbersome to you.
I personally do not have a problem with UI, Pagure is just fine and works as expected. Although, the process and scope of the Quick Docs needs a lot of work.
What constitutes a Quick Doc ?
What should the scope of a Quick Doc be ?
For example, I am looking into translating several Quick Docs, this process has become arduous because some of the Quick Docs are outdated, meaning they would need to be updated and grammatically fixed before anyone should undertake translation.
Earlier post on this thread show I was leaning towards the 1 solution of the Quick Docs, though I’ve become disillusioned by the process, scope and bureaucracy.
At this point, I’m more inclined to simply create the Docs, well formatted and grammatically correct and post them here, including translations.
Works for me. Even though a subcategory named “Guides” could be clearer.
Also, I found out that there are a few guide posts in Ask Fedora , could that be merged with howto ?
I have some experience with Fedora Wiki translations and I always felt that they bring more harm than good. When users are served outdated content, possibly by years or a decade, and they don’t know about it, it’s a terrible service. And nowadays a machine translation works very well and it can be much better to serve machine-translated up-to-date and working instructions, than human-translated outdated and broken instructions. So, I’d personally only support translations where the system in question natively supports it (and well, meaning users can easily see all available translations from the original document and select it, and translators can see what the original document for a particular translation is and compare whether it needs some updates). That’s Fedora Docs/Quick Docs, but Wiki is just borderline (the comparison is much harder than with git), and I see no support in Discussion (or is there?).
Of course we can’t prevent people from translating posts, but I wouldn’t encourage people to do so officially. If human translations are needed, nudge creators to a place which better supports it.
Probably. I need to untangle a tag group setting for guide and make sure I don’t block people using howto in categories where guide is now allowed but howto isn’t.
Should it be easier to add how to category straight for common ones and move them there example there is mine howto davinci on fedora it needs updating but I can’t edit the original post and it is spreading on different parts now
On the category I mean howto guides there straight forward and more details on to how to there is links to wikis and troubleshoot for more information. People are coming here mostly first and that would help ask fedora parts too and tags
Good idea @kparal. I would propose to make a subsection in ask like knowledge or knowledge-base. Then users who get annoyed notified while we change some tags on older topics, then they can exclude such kind of subcategory for tracking.
And we should more use the tags while writing answers to the users. Like:
Please have a look here howto and search for davinci (to take an example mentioned above).
p.s.
And users who complain that we push older information to the top while setting a tag, they should try the view new instaed of active.
There is also a default setting of 3 minutes reading to get a topic tracked. Maybe put this value to 10 Minutes also changes the notification behavior.
I know that we never can make it right for all of us … but at least looking for a compromise would be something
but the English version would not be compatible, as it is overwhelming for a Layman/New User (or new user looking for a quick solution) which can be tense moments.
