Migrate Quick Docs from Docs site to Ask?

Agreed - and it has to be at the place where he/she is looking for it so that the user can find it :wink: Besides the advanced users who know what they are looking for and where to find it (due to advanced background knowledge and knowledge of the Fedora organization), you will find another (big) group of users in ask.fp (and elsewhere): a group that asks less sophisticated questions and that needs issue-/event-oriented structures to answer these questions and find what it seeks.

But given your recent points about the outdated quick docs and such, I think we are already widely on the same page. Expanding the “common issues” seems a compromise that might provide better (issue-/event-oriented) structures for ask.fp users. Maybe that does not even need to focus on the Quick Docs, especially if they are outdated. It might act as a second structure that is quick and issue/event-oriented, and that points to the related non-quick docs pages? Of course the latter might include both quick and non-quick docs, whatever suits the solution best.

In light of the above and of …

@mattdm what do you think of the basic idea?

I’m not completely opposed — and it makes sense just based on the name. But that has traditionally (on the wiki) been focused on issues related to specific Fedora Linux releases, and linked to QA (documenting problems that we know about but don’t have a fix for, or for which a fix is pending, or where some intervention is unfortunately needed).

And that’s really useful too, and I think just mixing the two together would be bad for both. Maybe a separate subcategory for the release issues vs common issues in general? @kparal, thoughts?

4 Likes

A separate subcategory makes sense to me.

I think, it is not a compromise but a much better solution, specifically regarding the issue-/event-oriented structures, you need for ask.fe. Such a structure is difficult to integrate in a systematic oriented documentation (nor you will find it in Quick Doc). And such a structure is extremely necessary and there is a high demand for it. Look at such sites as serverfault.com or superuser.com

I’m a big fan of Stack Exchange, but I think those sites don’t do a great job of really producing a curated list of top answers. There’s amazing stuff there, but it’s mostly found through Google, not through manual selection into a category.

2 Likes

Sorry, can you give me a tldr version of the question? And some actual examples of what would go into each category?

So the normal workflow is to first file issues pointing out what needs to be changed. We then discuss what needs to be done in the issue, preferably with someone with sufficient knowledge about the subject of the page under discussion. Then, once there’s a plan, someone can take on the task of filing a PR.

This is no different from any other writing related project—there’s a place to discuss what’s wrong and what needs to be done, and then the actual changes are reviewed separately in a pull request.

I think the installation guide and admin guide are quite specific documents. I’m not even sure of what the process for them is nowadays—who writes them, who maintains them—but the new community driven documentation is intended for everyone to be able to participate/contribute/review/accept in changes.

Again, the admin/installation guides are specific cases that will need looking into.

The issue with “an author wrote an article” and limiting things to them is that they become the single point of contact and failure. If they leave or go inactive temporarily or are just too busy to respond, no one else will then be able to modify the docs. The whole idea of collective documentation is that we all share knowledge and responsibility. Community volunteers need to be able to take time off without worrying about who will take care of things while they’re away—and that can only happen if they’re not the single point of contact/failure. (Take the package maintainers team for example, there’s a reason why we have the non responsive maintainer process, and why we try to form smaller teams that can collectively look after packages, and why we have a setup where in extreme cases “provenpackagers” can push urgent fixes.)

So, instead of limiting ourselves to the author that wrote the article initially, we should involve absolutely anyone in the community that has the necessary knowledge—by e-mailing the -devel list for help for example.

There’s really no question of appreciation/respect here. We’re not being disrespectful by improving/maintaining the page. We need to stop thinking on those terms. If I’ve written a doc and someone goes ahead and improves it with or without my knowledge, I will remain forever grateful—because if I’m marked as the single point of contact, then it is my and only my responsibility to keep that resource up to date.

We (or at least I) do not want single points of contact/failure.

PS: The biggest advantage of anything git based is that all changes can be easily reverted, so we rarely worry about something wrong happening—it’ll get noted and updated/reverted/fixed—and it all happens in the open.


PPS:

I still feel that we’re trying to solve a lot of “lack of human resource” issues by moving things around here and there on to different platforms. It doesn’t matter if things are on Git/Antora or Ask Fedora or the Wiki. If we don’t actively encourage more people to work on docs, it’ll all remain outdated. I’d be much happier spending resources on getting more people working on docs, for example with a virtual FAD (Fedora activity day—we used to have them in the past) or something, than on migrating things from point A to point B (again). The current docs tooling is very good and is improving all the time to add missing features. We’ve migrated a massive cache of information from the Wiki, and we haven’t even managed to review and update all of it. Moving it again will not solve this.

2 Likes

No, they don’t do that. I meant it as an example, how strong the importance of and the demand for event driven information is. And what a great opportunity it is for us, to expand ask.fedora in that direction (and that it is not “just” a compromise). And we might get it better and realize exploration/cataloguing via categories. That would be really a challenging and most interesting project.

1 Like

tl;dr — there are “Common Issues” like we have with current releases, but there are also long-standing “Common Issues” that people need help with all of the time. How to partition a disk, how to set up a firewall to better secure your system, how to get the [insert swear words] Nvidia driver working, etc. Basically a “Fedora Users’ FAQ”.

2 Likes

That’s fine for me, unless that I missed the discussion part (until the revitalization meeting, that is).

I don’t know, why these should be special. Anyway, we are in the process to update the installation guide as a PoC.

We don’t want a single point of failure. You discuss the worst case, when an author is no longer available. In case of this I completely agree. But when an author is still around and member of the community, I prefer to make contact in advance. Maybe it is a bit “old fashioned”, but that’s me.

Me too. But the people who are working on the tooling, are not those, who will work on the content. At least, that’s how it looks to me. And we have still to develop our organisation and workflow. But after such a long time of stagnation, it takes time.

I don’t consider those “issues”, but rather “tasks” / “guides” / “how-to’s”. I don’t care much whether those guides live in Quick docs or Ask, but I’d like to have them separated from Common Issues (if you want to name the guides as issues, then Common Issues could go back to Common Bugs, or Release Bugs, or similar, I don’t have a strong opinion on the name). But it would seem clearer to me to name them e.g. “guides”. (Common Issues can still get renamed, if people find a better name).

I’m not sold on placing one of them inside the other as a subcategory. Which one would be the top-level one? They both seem to be quite distinct concepts, so I think they should be separate categories (on the same level).

Besides the question of another category and additional issues/guides/how-to’s for ask.fp, it might be generally worth to think of renaming the “common issues”, even if we finally choose to not introduce anything new to ask.fp.

Most people who visit ask.fp are no Linux developers or engineers. They link the term “issues” to something else: to the problems they experience. “Common issues” can be very confusing because it is very generic and may be differently interpreted by different audiences. I would assume, most (or at least many) ask.fp audiences will interpret “common issues” the way @mattdm described it above: how to make my nvidia driver work? This question does not consider if the origin of the problem is a technical bug or limited user knowledge (many will not be able to determine that themselves anyway).

The name maybe should indicate that the current category of “common issues” does mean issues that originated in the technology (or more specific: in a given release; bugs, and so on) and not issues that originate in the user (due to absence of knowledge/experience). Maybe what is currently called “common issues” could be renamed to “release issues” or “common bugs”. Or something like that. I do not want to open another topic as we have already sufficiently to discuss, but I think a bit that we miss to address much audience of ask.fp :slight_smile:

It was called Common Bugs the whole time before migrating to Ask :smiley: I’m not a native speaker, I can’t really say what’s best, but have no trouble renaming it.

2 Likes

I didn’t know that :joy:

This is my fault. Here’s the distinction I’m making:

A “bug” is a software defect. [1] An issue is a problem that a user might encounter. That might be caused by one or more software defects — or it might be a misconfiguration, a misunderstanding, or even a misalignment of expectations.[2].

Basically: QA deals in bugs, but it’s really issues that users face, so that’s what I wanted to present. I think this could include some things like “I have an Nvidia card and graphics don’t work” — that’s not a task or a guide or how-to, really.

Kamil, am I making sense? It’s been a long week.


  1. Pedantically, examples of “common bugs” are things like “off-by one error” or “buffer overflow”. Commonly-Encountered Bugs might be better. But that’s not my point. ↩︎

  2. “This software doesn’t act Iike I think it should” ↩︎

4 Likes

I thought of this discussion while reading GNU Parallel’s 20th birtday blog post GNU Parallel's 20th birthday - Free Software Foundation because it contains:

Timestamps for the video (easy to understand with 2x speed):
introduction: What nobody tells you about documentation - YouTube
type: tutorials: What nobody tells you about documentation - YouTube
type: how-to guides: What nobody tells you about documentation - YouTube
type: reference: What nobody tells you about documentation - YouTube
type: discussions: What nobody tells you about documentation - YouTube
summary: What nobody tells you about documentation - YouTube
Q&A section: What nobody tells you about documentation - YouTube

We talked about guides and now we have a first one:
https://discussion.fedoraproject.org/t/how-to-load-nvidia-driver-with-secure-boot-enabled-on-fedora-36/75807

This is not a release bug in the usual sense of Common Bugs/Issues, but a long-term guide applicable to probably any release. So if we want to have it on Ask, we should probably have a special section for it. Or redirect people to create it e.g. in Quick docs, but that’s not as open and approachable as Ask or wiki. I consider Quick docs to be targeted at official documentation with a higher quality standard than standard community guides. Both should have a place to live, I think.

2 Likes

I think as we’ve noted there, this particular piece of information should really live on the RPM Fusion docs themselves. I’d consider the RPM Fusion nvidia how-to a guide, and if that were to be put somewhere in Fedora space, quick-docs would be the right place for them to go. For example, we have a guide on using Nividia optimus hardware on quick-docs which originated from a discussion on Ask Fedora:

Quick docs are exactly meant for this:

“This is a collection of short HOWTO and FAQ-style documentation for Fedora users”

1 Like

I would very much assist that! Quick Doc is exactly for that, but currently widely kind of misused. Anyway, everything, that fits into this category, should actually reside there! We have so many such different things in so many places, it’s very cluttered and confusing, especially for new users. There is one exception, if a how-to or FAQ on a specific big topic is covered in the context of another guide, such as CoreOS or Server.

Yesterday I had a very interesting discussion with Anushka Jain, one of our applicants, about categorizing articles and Quick Doc as a possible sample case study for analyzing and developing improvement proposals or planning. If we could make that happen, it would be a big step forward, IMHO.

4 Likes

A great thing: issue-based & problem solving-oriented, fits perfectly into ask.fp. But for users an issue is an issue, unrelated if the origin is technical or not (e.g., the example above: how to partition or encrypt disk), so that might fit there, too? I think focusing on that makes more sense than moving the traditional Quick Docs to ask.fp, especially because of the structuring. I would love to focus contributing to that approach.

But as already discussed, it should become a separated category. I like the differentiation @mattdm used previously: release issues & common issues. Although, if we use that, it might make sense to add a sentence to the top of the “new” common issues that what used to be the common issues is now the release issues (at least for some time; to avoid confusion).

I would avoid FAQ, imho FAQ is not about problem solving but answering general questions, isn’t it? I would link a FAQ in ask.fp more to an introduction to the rules of the page, how to conduct in the forums or something like that.

Btw, ask.fp issues and (quick) docs might also link to each other (primarily the first to the latter of course): that might be a good way to lead new users (who tend to end up at ask.fp when trying to solve an issue) to the docs (… another pointer to the same content : ) and avoids redundancy. So, more a soft than a hard separation. I see both complementary to each other and as a symbiosis rather than in competition. Might also facilitate new authors. Ask.fp also enables (and motivates) users to give feedback to content.