Migrate Quick Docs from Docs site to Ask?

[mattdm (Matthew Miller)]

Continuing the discussion from Fedora Docs and Ask.Fedora: a symbiosis?:

I’m thinking about this some more, and the Quick Docs in specific. I think that if we’d had Discourse for Ask Fedora back when I started Quick Docs, I would have put these on Ask.

In fact, I might have been tempted by the Discourse Docs plugin for the docs engine entirely. It’s not perfect, but clearly neither is the existing solution.

At this point, I do think the docs system is doing a lot that Discourse really isn’t good for, so I’m not at all advocating a general move, but… maybe we should consider moving Quick Docs in specific. As we’ve gotten more and more of those, the lack of search is getting more and more painful — and we didn’t get online editing to be as magical as I’d like. I’m still 100,000% sure that moving that stuff away from the wiki was the right thing, but maybe it still has too high of a barrier to entry, and (crucially) to continual improvement.

What do you all think?

[bcotton (Ben Cotton)]

This feels like an abuse of Discourse. In particular, I’d be concerned about the fact that we’d be spreading our user documentation across multiple platforms, which doesn’t aid discoverability. (And since some documentation is still in the wiki, there would now be three places.)

I agree that a lack of search hurts us, but I think this move would be a net negative. In particular because we’d be losing the ability to easily cross-reference between Quick Docs and… Unquick Docs. Moving the source to GitLab would improve the magic in our online editing, as I understand it, and that’s something we’re actively looking at.

[py0xc3 (Chris)]

@bcotton

spreading our user documentation across multiple platforms, which doesn’t aid discoverability

Docs should be where the users are looking for them. The preferences (how/where do users search and therefore, where do they end up) of quick docs users and long docs users could be different (that is not an argument, but an open question that we have to evaluate). If these preferences are different, splitting the docs may increase (the respective) discoverability. But if the preferences are comparable, splitting docs may indeed decrease discoverability.

On one hand, I would assume that quick docs users are more likely to find what they seek on ask.fedora. Many end up at ask.fedora, which we see in the many threads/questions we have. At the same time, I would assume that most “average users”, which are mostly interested in quick docs, do not know about docs.fedoraproject.org. It is easy to get there when I know the url - but I have to know it: I just tried to get to the docs by starting at fedoraproject.org → I get the Fedora editions and spins, and learn how to join the community, but no way that an average user will find docs that way (maybe it makes sense to also talk about adding docs more obviously on the main page? In the support section on the bottom at least? ask.fp is already there, but not docs).

Therefore, this links to the other issue we already discuss: Search Engine Optimization. Most users use at first their preferred search engine, making SEO a big issue in terms of discoverability. I think search engines are currently the major path to docs.fedoraproject.org.

Thus, does splitting the Docs negatively impact SEO rankings? I think that potential issue has to be considered.

I think we first have to identify: where/how do users search long docs, and where/how do users search quick docs? This may start with first asking which users use quick docs and which users use long docs (“which users” mostly in terms of knowledge/experience level: this determines how and where they look for something / formulate queries). Of course, in all that, we have to keep the potential SEO issue in mind (and maybe talk about making docs more obvious on pages that users tend to visit, to less rely on search engines).

A very probabilistic & experimental thing in my opinion But I tend to give the Docs plugin at ask.fp a try. It might also bring the teams closer together and foster integration.

[pboy (Peter Boy)]

@mattdm

As we’ve gotten more and more of those, the lack of search is getting more and more painful

Well, we now have a search function (in staging at the moment). There are some slight issues, but grosso modo the advantage outweighs the disadvantage right now.

@mattdm

… and we didn’t get online editing to be as magical as I’d like.

Online editing and “quick” is one side, documentation quality and accuracy the other one. Quick Doc’s accuracy already leaves quite a bit to be desired in many areas (eg. about virtualization or partitioning). I’m afraid online editing doesn’t necessarily make it any better. In any case, it requires editorial supervision. It might be more helpful if we had a comment function (like partly in the Apache documentation). That way, we would have a clear separation between “approved content” and “loose experiences”.

[ankursinha]

@pboy

Quick Doc’s accuracy already leaves quite a bit to be desired in many areas (eg. about virtualization or partitioning)

Could you file issues for these please?

I don’t think what platform we use and what comments/feedback features they have matters much tbh. The only way to ensure that the docs are accurate is to encourage folks in the community who specialise in subjects to review and update docs involving them. So, lets file issues about inaccuracies, and open PRs where we can or reach out to other community members to request help when we’re out of our depths.

[pboy (Peter Boy)]

@ankursinha

Could you file issues for these please?

I appreciate (and admire) your indefatigably. I must admit that I hesitate a bit to add to our 40 or 50 overdue issues another one, probably unheeded for another 2-4 years, as those already existing ones.

But nevertheless, you are right, of course. But where is the right place for an issue or pull request? I’m pretty lost in the sheer number of repositories of varying timeliness and quality.

@ankursinha

I don’t think what platform we use and what comments/feedback features they have matters much tbh.

Objection here. The Pull Request workflow is quite elaborate and quite a high obstacle. At least, I am a bit reluctant to clone tens of repositories and shovel my hard disk to change a small part of a documentation, and with a doubtful success, because it is completely unclear what happens to the PR.

And as an author by profession, I very much respect the author’s sovereignty over his text and don’t like to fiddle with it without asking first.

[pboy (Peter Boy)]

@py0xc3

… preferences … of quick docs users and long docs users

If I remember correctly, there was no concept or different users, but of amending documentation. When introducing QD there were just the Installation Guide and the Administrator’s Guide (and die “old” docs). All of them monolithic and hard to maintain. QD changed over time in a kind of “permanent alternative” docs, though.

@py0xc3

On one hand, I would assume that quick docs users are more likely to find what they seek on ask.fedora.

Both are very different kinds of learning and information gathering. Docs is the quiet, non-interactive - reading space for the lonely individual in the library; ask.fp is the interactive, discursive community space. We should not mix the two.

[py0xc3 (Chris)]

@pboy

If I remember correctly, there was no concept or different users

We do not decide if the users of quick and long docs are different. They are different or not. We can only choose to consider it, or to ignore it, if it is the case.

@pboy

Both are very different kinds of learning and information gathering

Different types of learning, but with the same goal and possibly, relevant for the same type of people. If an average user wants help, it can be ask.fp or the quick docs, or both. People ask questions and Quick Docs can be the answer (I’m quite sure in many cases people simply do not know the Docs). If a user (whose problem is explained in the quick docs) ends up at ask.fp, the quick docs could make a difference if they are at the same place.

@ankursinha

The only way to ensure that the docs are accurate is to encourage folks in the community who specialise in subjects to review and update docs involving them

That’s a very important point. And it is one where I could imagine that moving the Quick Docs to Fedora Docs will have a positive impact: the entry barrier to work on the Docs seems much lower with discourse. Also, many more community members then get “in touch” with it and thus, become motivated to contribute.

[ankursinha]

@pboy

I appreciate (and admire) your indefatigably. I must admit that I hesitate a bit to add to our 40 or 50 overdue issues another one, probably unheeded for another 2-4 years, as those already existing ones.

That’s a human resource problem though—we know that we need more people working on the docs. Moving it to a different platform will not fix that. We’ll just have 50 overdue issues in a different, new place

@pboy

But nevertheless, you are right, of course. But where is the right place for an issue or pull request? I’m pretty lost in the sheer number of repositories of varying timeliness and quality.

Each documentation page has “edit this page” and “file an issue” links in the top corner. So clicking those takes us to the right place.

@pboy

Objection here. The Pull Request workflow is quite elaborate and quite a high obstacle. At least, I am a bit reluctant to clone tens of repositories and shovel my hard disk to change a small part of a documentation, and with a doubtful success, because it is completely unclear what happens to the PR.

One doesn’t necessarily have to download anything. I use the web-interface a lot, which will be even nicer after the move to GitLab (or so I’ve read in a discussion somewhere?).

What do you mean by “what happens to the PR”? A community member reviews it with you and then when you’re both satisfied, it gets merged. It’s a peer-review step which will need to be incorporated into whatever workflow/platform is used. The advantage here is that anyone can submit a PR, and anyone can review it.

@pboy

And as an author by profession, I very much respect the author’s sovereignty over his text and don’t like to fiddle with it without asking first.

I don’t think your concerns apply here. Authors to community documentation do not have ownership over their text, just like package maintainers do not have ownership over their spec files. These are community resources and everyone in the community (as long as they have the right permissions/access) can modify them. That’s sort of the whole point of community based documentation—we maintain it together.

[py0xc3 (Chris)]

@bcotton

We don’t have an SEO team, and limited programming help available. But with the client-side search that darknao is implementing, I’ve noticed that the results are sometimes not particularly helpful. We’ll have to work with the teams that maintain each docs module to help make sure their page titles are helpful in a search result context.

It might be added that the discourse search function is, at least in my experience, good in providing related results. But I also understand the counter-arguments against the migration to ask.fp. However, there is not only the yes or no answer but also compromises.

If we in the end decide to not move the quick docs, it might be still a good complement to make more use of the Quick Docs in (especially but not limited to) the “Common Issues” in ask.fp.

We can add “common issues” that are simply problems we often see in ask.fp threads or issues that are no problems but applications with which users regularly struggle - and then provide the link to the respective quick docs… Examples would include qemu/libvirt, NetworkManager.

For the average user, a common issue is something they experience and something they want to get rid off: this is their generic way of defining common issues. So maybe we can also make it more generic and use it as compromise to promote quick docs without moving them?

Therefore, in short, we create pointers from ask.fp to the Quick Docs instead of moving everything This would enable the search capabilities of discourse and may lead users (who usually end up at ask.fp) from ask.fp to docs.fp.

An issue/problem-oriented structure is maybe more suited for ask.fp anyway (because it is possibly easier for average users and their challenges) compared to the original quick docs (while advanced users might feel more comfortable with the latter). Thus, these two structures leading to the same content may make sense anyway to keep all types of users on board?

[pboy (Peter Boy)]

@py0xc3

@pboy

If I remember correctly, there was no concept or different users

We do not decide if the users of quick and long docs are different. They are different or not. We can only choose to consider it, or to ignore it, if it is the case.

Or they might not be existent. There is no"long docs". And quick docs and other docs do not deal with the same subject, just in a different form. We have no “long docs” vs. “quick docs”.

A lot of articles in Quick Docs are outdated. A “Quick Doc user” would be mislead. Other currently Quick Doc articles will be integrated ( moved into other documentation as they are updated. An example of this would be the QD article on virtualization.

A good candidate for AskFed would be FAQ.

[pboy (Peter Boy)]

@ankursinha

That’s a human resource problem though—we know that we need more people working on the docs. Moving it to a different platform will not fix that. We’ll just have 50 overdue issues in a different, new place

I agree. The problem is, it is a vicious circle: few people → lots of unfinished business → even less motivation for people → even more unfinished …

@ankursinha

What do you mean by “what happens to the PR”?

My point was that I - and perhaps other authors - are not particularly inclined to put a lot of work into a PR without first knowing if it will go in an accepted direction. I’m happy to do a PR to correct a comma or a typo, but I wouldn’t do extensive updates that way. I would like to discuss beforehand in which direction it should go. Like currently with the installation guide.

I made suggestions about the Installation Guide and Administration Guide about a year ago. No one has responded to them in terms of content, only the suggestion that I write a PR. But I have no inclination to spend 10 hours of work and more in a PR that then rots away for 4 years or forever.

@ankursinha

I don’t think your concerns apply here. Authors to community documentation do not have ownership over their text,

Well, I used sovereignty, not ownership. And I agree with community resources. On the other hand, have a look onto our Installation and our Administration guides, a long part about copyright etc.

But more important: if an author wrote an article and probably still works on the subject or is interested therein, I would really prefer to discuss a modification beforehand instead of just make a change. For me, it is a matter of appreciation and respect, not legal issues or licensing requirements.

[pboy (Peter Boy)]

@py0xc3

We can add “common issues” that are simply problems we often see in ask.fp threads or issues that are no problems but applications with which users regularly struggle - and then provide the link to the respective quick docs… Examples would include qemu/libvirt, NetworkManager.

I think that’s a good idea. Might be comparable to a FAQ that I suggested in another thread.

But not only links to Quick Doc, but to the corresponding documentation. As an example, QEMU/libvirt in Quickdoc is mainly for graphical workstations (but also partly obsolete), for servers misleading (without being mentioned). For the latter there is a special server documentation.

[py0xc3 (Chris)]

@pboy

Or they might not be existent

What do you mean?

@pboy

There is no"long docs".

Sorry for that. I intuitively used a term from another project: I simply meant the docs that are no Quick Docs.

@pboy

We have no “long docs” vs. “quick docs”.

It was not my intention to indicate a “vs.” issue. However, the thread is about moving the Quick Docs but not the remaining Docs. Therefore, we have to differentiate in this thread between Quick and Non-Quick Docs.

@pboy

A lot of articles in Quick Docs are outdated. A “Quick Doc user” would be mislead

This is indeed a strong argument! But if the Quick Docs are misleading, they are maybe not useful for any page at the moment: in that case, we might discuss to set outdated Quick Docs offline until the outdated issue is sufficiently solved?

[pboy (Peter Boy)]

@py0xc3

@pboy

Or they might not be existent

What do you mean?

There may be no “quick doc user” nor a “long doc user”. A user uses what provides an answer.

@py0xc3

@pboy

We have no “long docs” vs. “quick docs”.

It was not my intention to indicate a “vs.” issue. However, the thread is about moving the Quick Docs but not the remaining Docs.

My issue is, you’re probably - inspired by the title - seeing something in "Quick Doc " that’s not in there at all. It is simply more or less an appendix to the “other doc”. It is pure coincidence what ends up in it. Not only that, it has nothing to do with “fast information” or anything like that. It is simply a way out, because the existing documentation was or partly still is cumbersome and time-consuming to maintain. A more appropriate term would be “Miscellaneous unsorted information”. But that is not so cool nor is it something that is needed in ask.fe.

I think, your idea of “common issues” is much more appropriate. Specifically, it could contain answers to very specific practical questions, that are difficult to include in a systematic documentation. Anything that begins with “How to …”

@py0xc3

But if the Quick Docs are misleading, they are maybe not useful for any page at the moment:

Yes, that is really an issue. And a matter of manpower. I guess, it is not before mid next year that we can do something about it. There is a lot of useful information, but also a lot of outdated and misleading information. To sort that out is very much work.

[py0xc3 (Chris)]

@pboy

There may be no “quick doc user” nor a “long doc user”. A user uses what provides an answer.

Agreed - and it has to be at the place where he/she is looking for it so that the user can find it 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 …

@py0xc3

If we in the end decide to not move the quick docs, it might be still a good complement to make more use of the Quick Docs in (especially but not limited to) the “Common Issues” in ask.fp.

We can add “common issues” that are simply problems we often see in ask.fp threads or issues that are no problems but applications with which users regularly struggle - and then provide the link to the respective quick docs… Examples would include qemu/libvirt, NetworkManager.

For the average user, a common issue is something they experience and something they want to get rid off: this is their generic way of defining common issues. So maybe we can also make it more generic and use it as compromise to promote quick docs without moving them?

Therefore, in short, we create pointers from ask.fp to the Quick Docs instead of moving everything This would enable the search capabilities of discourse and may lead users (who usually end up at ask.fp) from ask.fp to docs.fp.

An issue/problem-oriented structure is maybe more suited for ask.fp anyway (because it is possibly easier for average users and their challenges) compared to the original quick docs (while advanced users might feel more comfortable with the latter). Thus, these two structures leading to the same content may make sense anyway to keep all types of users on board?

… @mattdm what do you think of the basic idea?

[mattdm (Matthew Miller)]

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?

[py0xc3 (Chris)]

A separate subcategory makes sense to me.

[pboy (Peter Boy)]

@py0xc3

Expanding the “common issues” seems a compromise that might provide better (issue-/event-oriented) structures for ask.fp users.

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

[mattdm (Matthew Miller)]

@pboy

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.