Hey folks. This past week, I was at All Things Open 2022. One of the sessions I attended in the Community track was titled Approaching Open Source Documentation the Right Way. I thought it was an interesting session, and I thought how the speaker framed documentation as a product was insightful. Along with some of the actionable, insightful tips he shared.
I live-tweeted the session, and you can find my Twitter recap of the session below. I am still digesting it, but there were definitely parts that felt especially relevant to Fedora Docs. One consideration that stood out to me was adding a small but notable data stream into the process, i.e. users upvoting or downvoting helpful pages so there is one data point on what is working well or what isn’t.
I wish another data type will be collected in addition to Up/Down vote. As Fedora is fast moving, to capture from which version a particular doc is applicable / not applicable will be helpful to readers.
Do you mean something like a button to flag, “This page is not up to date with the latest Fedora release”? Or an open field for anyone to add a tag like “f37”, “f38”, etc?
I like that idea. Given the limited contribution, we have Docs pages that are not updated since Fedora 21 (21 → end of life 2015). A short click from those who end up at such a page (and that have the necessary experience) on a button “applies to 35” or so would be indeed add valuable information for following readers, especially the beginners. Especially the Quick Docs would profit from something like that. But the implementation of that unfortunately would be another thing for both organizational/social and technical reasons I guess…
In addition to tell the readers if those Docs still applies, I hope it will also give extra indication that certain section of the Docs is outdated - then may be some automation can create a task list so that “Doc Authors” can pick up and contribute quickly.
Unfortunately, I think it is unlikely that the Docs framework can be easily tailored to support any of this. It took already noteworthy efforts and testing to deploy the search function. That software is not as “plug and play” as discourse. I never maintained/administrated Docs infra myself, but given the discussions we had about it over time: concerning enabling any user to persistently manipulate stored data (such as thumbs up/down, applicable to F36, etc.) without logging into FAS, I guess the barrier to get this securely implemented is much higher than that of the search function.
Well, the missed options to “vote down” or “vote up” or any “tagging” mentioned in previous posts are just bad habits and means for mindless opinion campaigns as known from misnamed “social media”. This has absolutely no place in a serious project and is simply nonsense.
Every page already has an option for feedback. In the bar just below the page title bar, you see an “i” in a stylized bug, i.e. “bug” in the sense of project development. And for someone who is not familiar with the jargon, the notice text says “report an issue”. This opens a form where you can state the problem exactly, where factual arguments can be listed, and where there are further opportunities for an argumentative exchange of possible solutions and improvements. This is the way in which a civilized community communicates, acts and successfully shapes the future. Not this mindless dumb “voting” and “liking” and similar bulls…
Sorry for my ragging. This in no way refers to you personally. It’s more a cultural critique and the negative effects on constructive evolution, of which Fedora is a (small) part.
Since the revitalization of the docs team in April this year, we are working hard not to miss any feedback and not to react to it. If we did miss, we should analyze that case to learn what we still have to improve.
I think, we have to monitor all documentation that is under our control. Another question is, how we can become aware of problems with other documentation and whether we should try to improve in such cases.
That’s true, I recognized a big change and effort about the new Documentation. Thanks a lot so far!
The search option is a very nice example. And it works great!
About our likes in discourse, they all seams to be positive except the question-mark where I would tax as neutral.
If we would use something like that for the docs the question-mark would make a clarification mandatory and could be used as request/feedback as an addition to yes/no.
For measurements searching requests could also give some feedback for missing documentation.
Since I spend more time with Ask and Discussion recently, I did notice the increased activities for Docs. As long as feedbacks got handled, I am sure the reader engagement will keep increasing.
I have another thought - not sure it is worth considering at this stage.
Given the that old Fedora Documents are still access across quite a few platforms, plus edit the old pages might not be possible.
How about create a central portal for readers to report dated Docs links from Internet Search Results?
Wikis can be many things — encyclopedias, workspaces, whiteboards, and more. While many great docs sites are built from wikis, we’ve discovered that mixing all of those things together really causes chaos. Our documentation resides on its own site and this wiki is strictly a contributor workspace.
If you’re a Fedora user, you’re welcome to browse around — see the subprojects menu at the top for some places to start.
Note that you’ll need a Fedora account and to be in at least one Fedora subproject group on that account to make wiki edits.
Yes✘ No