All Things Open 2022 session on docs: "Documentation as a product"

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.

1 Like

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… :frowning:

1 Like

Depends on what kind of feedback machenism Discouse can provide.

As a minimum, a One click feedback to indicate “this no long works for the latest released Fedora” .

For more involved feedback, I might want to tell others that “This stops working since F35”, etc.

Of couse, making good use of label can do, like:
Works on F33
Not Work on F35

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.

1 Like

Could something like the extra bar below the title, that Server documentation introduced, be helpful, specifically for Quick Docs?

1 Like

The way it displays the applicable versions are great!

My next questions will be - how to allow “authorized” readers to give the feed back.

For example, if when F37 beta is released, and I want to add “This does not work with F37 Beta”, etc.

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.

From my previous experience, once I discover my (valid) feedbacks are being ignored, then I will not bother to give feedbacks any more.

So, in order to keep the site healthy, please do allocate enough resource to take on feedbacks and act accordingly, and quickly.

In this regard, those “likes”, “flags” that can be immediately reflected without delay will be useful to increase readership.

Right, it is culture question, and how to measure sentiment. Here is what I think about social aspect of user/community feedback.

  • Feedback is valuable.
  • It depends on how we design feedback question and loop.

A neutral way to gather feedback looks like

Is this article helpful?

:heavy_check_mark: Yes✘ No

Another way as outcome-driven survey design is
Does this FAQ solve your problem (or provide a solution)?

I think outcome-driven question is more suitable than smiley/frowning face or down/upvote or like/dislike emojis to measure docs.

We also need to consider what type of articles we want to monitor.

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?

The report should include:

  1. Search Engine URL used
  2. Search string used
  3. URL of the dated Doc
  4. The ranking of that URL in the search result.

For example:

  1. Google
  2. grub uefi fedora
  3. GRUB 2 - Fedora Project Wiki
  4. Top result

The Fedora Wiki does not belong to the Docs :wink:

See the bottom comment “This Wiki” of Fedora Project Wiki :

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.

1 Like