Would someone love to rewrite top answers on audio issues to Quick Docs articles?

I had an inspiration from a previous post on ‘Magazine to Quick Docs conversion’. So, I’m taking an initiative to rewrite solutions in Ask Fedora for Quick Docs articles. Rather than converting solutions to Quick Docs as they are, I believe rewriting solutions as troubleshooting guide would save time in the long run.

All we need is to find volunteers and subject matter specialists to take on rewriting them for Quick Docs. There are good solutions that were answered in different posts.

I presume combining several (related) solutions as an article will serve more readers who want to solve problems. Quick Docs has the highest views in the entire Fedora Docs pages (including all edition Docs).

How about trying one subject matter and getting this off the ground? Afterwards, we can expand this to other Ask Fedora categories like video, kernel and so on.

I have searched common issues and solutions around audio and all tags related to audio and sorted by views. There are a couple of posts over 10K views on audio related ones. I picked three tags in Ask Fedora and am looking for volunteers in 2024.

  1. PipeWire

  2. Audio (need to shortlist top criteria as it is too broad)

  3. PulseAudio

Thanks and wish you a very best of 2024!

(Edited Jan 2 2024]

I added a poll to get your feedback on this idea to rewrite solutions to Quick Docs articles. If you think the idea is good, click yes. If you object to the idea, click no.

New articles using solutions in Ask Fedora
  • Yes, that’s a brilliant idea!
  • No, we don’t need to repurpose solutions made in Ask Fedora for Quick Docs articles.
0 voters
2 Likes

Before the poll closes, I’d love to hear from docs-team (Board member and committer group) and Music & Audio SIG admin @nphilipp and members. Please share your views. Thanks a million.

I think this is a fantastic idea. When we first launched the current system of Fedora Docs in 2018, our goal back then was to migrate valuable Wiki pages into better organized Fedora Docs to make them easier to discover.

I like the idea of starting with audio issues because it is a smaller scope and not as overwhelming as tackling all Fedora Ask questions ever. If the approach works well, it could be extended into other topics too.

One thing that I think a new contributor might need is knowing how to get started. If we are making an ask, we should come up with a good call-to-action and then enlist help from the marketing-team. I think a good call-to-action might look like a job description of sorts:

  1. Skills required
  2. Description of job
  3. Technology and tools needed for the job

For this project, skills required would be technical writing and content management. The description of the job would look like a description of the task to complete, and maybe an example of a similar end result. The technology and tools needed would be AsciiDoc, basic git, and optionally, some container development tools.

1 Like

Thanks for your suggestions.

About skills and description of job,
I believe we need a small group of reviewers on Pipewire and ALSA (Advanced Linux Sound Architecture). General skills required are troubleshooting and bug triage, which help validate solutions proposed in Ask Fedora, dedup/consolidate them, draft content and advise what research we need.

About technology and tools,
Quick Docs repo in Pagure and discourse will be a central point.

One way to achieve this is to open a post in discourse about a topic (best with a template) and get a minimum of two votes to raise a ticket in Pagure. Assign a ticket to a writer.

I took an idea from the Magazine team workflow as well as Community Blog.

2 Likes

Finding pertinent information is often harder than it needs to be, compiling information and providing it in a structured way must make this easier, so I’m all for it!

1 Like

Really, IMO the Magazine is the place to have this “call to action”. For proof, just see the uptake of posts submitted by non-usual contributors to the magazine directly after such type of an article is published for magazine contributions.

2 Likes

While I’m waiting for feedback from docs-team (Board members and committer group), I’d expect the followings;

Data analysis

  • Shortlist top 10 article topics from Ask Fedora and get them reviewed

Communication and wrangling: by 29 Feb

  • Put key message together and write a draft for the Magazine
  • Publish CTA to the Magazine
  • Looking for proposers for each article topic
  • Following up with proposers to article summary and plan

Writing and review: 1 Mar onwards, hopefully :slight_smile:

  • Article proposal and assignment
  • Writing articles
  • Pull request to Quick Docs
  • PR review before publication

Poll will close on 18 January. If you have any questions or something I overlooked, please let me know.

@pboy I hope you’re well. I wish to have your feedback in time. Thanks.

Hi all, here is a list of article topics about audio issues and how to guides. WDYT?

Issues

  1. Audio input not recognized
  2. Volume level set to 0
  3. Noise and anomalies: crackling sound, latency, clicking, distortion
  4. Reported issues on upstream (resolved and open) and known hardware issues

How to guides

  1. Set up external device and interface
  2. Optimize audio settings for better recording quality
  3. Jack-audio-connection-kit (JACK) and pipewire-jack
  4. When you absolutely need config change and when you must stop messing around config files
  5. Realtime kernel: when you must use it?
  6. Control Applications

Use cases

  • USB devices
  • Video call (Jitsi)
  • Screen recording (OBS Studio)
  • Digital Audio Workstation

I’ll wait for feedback and resume next steps sometime in February. Thanks.

2 Likes

Hi,

I got some useful feedback in another discussion, but I though it would be more constructive to reply in this thread.

I linked to the ArchWiki as a basic source of truth with the assumption that most Fedora users would find it convenient to fact-check / check for article updates before committing to modifying their setups.

I actually got the gumption to create my first post when it was clear plenty of Fedora users either don’t use or know about ArchWiki. This includes both new Fedora users creating posts and not finding wiki information that’s written in plain text, and it also includes Fedora veterans with good intentions who provide outdated or questionable fixes.

This might have to do with Fedora achieving “Normie Status” (and Windows 10+ turning into a wrapper around a virtual Las Vegas strip-mall). It might actually be the case where the modern Zoomer has never heard of or Googled or TikTok trended the string “ArchWiki”, but you say “Fedora” and they say “Oh, isn’t that Linux? I heard the Linux guy uses Fedora.”

Discourse has helpfully created some metadata links to other users encountering the same issue in the post I created (scroll down to Related Topics).

If you follow the rabbit hole of these threads, you’ll see Fedora users asking for help, playing kernel parameter roulette, getting endlessly frustrated, and being told to stop thrashing around, nuke pipewire using dnf --allowerasing, and replacing it with pulseaudio.

No, no, no!!!

It’s a single, 257 byte drop-in file. 20 additional bytes for the folder tree on btrfs. What a tragedy.

Yes, lots of fixes are available in places like ArchWiki, but ArchWiki is randomized through human error. Anyone who’s gone deep into ArchWiki knows it’s very easy to find yourself 3 hours in, totally overloaded with information, dozens of tabs open, and you just miss stuff like this.

I would argue yes, it is indeed, easy to miss ArchWiki article: PipeWire: section 5.1.13, and no, it’s not enough that ArchWiki exists, and Fedora exists, so therefore Fedora users will intuitively connect the two.

It needs more links and metadata on the fedoraproject.org side, so users who encounter this issue have at least a fighting chance of getting on with their day, with as little time wasted as possible.

Also, you’ll notice the fix for this actually is on the WirePlumber side, not the PipeWire side. If you don’t send the right strings to your search engine, they seem great at not picking up on these kind of basic connections. Also we’re assuming the Fedora user even knows or can figure out they are running the PipeWire audio server plus WirePlumber, or that they even know what an audio server is!

At the very least I’m hoping the post saves a few users from taking the drastic step of force-swapping their distro-recommended audio server just to stop popping noises!

I’m also on Immutable KDE and the thought of someone rpm-ostree overriding pulseaudio in desperation actually triggers me.

I’ll just chime in here and say if there already were a Fedora Quick Docs or HOW-TO section, my intuition would have been to post the crackling audio issue to such a section. When I ended up picking Proposed Common Issues, it did not intuitively seem like the right place to post a snippet, but it seemed like the least bad place to get feedback, and the best place to get the post into the least bad sub-forum.

Ask Fedora kinda works if you squint, but people there are mostly getting individual problems solved and they move on. Having long back-and-forth threads mixed with short answer snippets in one sub-forum is clearly not the best UX.

I think a unsaid truth here is that somebody posting something on the Fedora forums is far from ideal compared to proper documentation, under source control, with an issue tracker and CI. As soon as I post my fix on the forums it’s technically outdated, I could get hit by a bus or retire and the post never gets updated, then it’s inaccurate, then it’s hurting instead helping.

I’ll also say having a bot that turns all Fedora Quick Doc entries into Discourse posts would be “nice”. I could contribute to the docs, close my Ask Fedora post, and know in the future if the problem changes or goes away, enough eyes will be on it to stay accurate.

Hi there, thanks for sharing your insights on discovery of solutions, issue of content freshness and pitfalls we need to be mindful of.

What we, as Fedora contributors, could do is to create top 10 most asked issues that are resolved in recent years (roughly from F34 release when PipeWire became a default audio and video daemon).

We don’t have a section on audio issues in Quick Docs at the moment. We keep getting similar or device specific issues users are struggling with.

I’ll publish call to action in clear manner in the Fedora Magazine, probably in March, asking for volunteers.

2 Likes

In principle, you are right. However, in reality, solutions accepted (see those satisfying tick-box “solutions”) and versioned documentation will co-exist. Helpers in Ask Fedora put massive efforts here to understand common or unique issues Fedora users encountered with.

That’s also true in many businesses where professional team of content producers, documentation writers, R&D/support engineers (there are great reviewers) work around the clock. They have backlogs in production. They also run community forums asking for user driven content and solutions.

2 Likes

I am somewhat skeptical about ArchWiki. It looks very good and comprehensive. In terms of content, in my experience it is largely a kind of “retelling” of the upstream documentation, sometimes structured a little more clearly. And many of the solutions offered are not suitable for Fedora.

I think our general strategy is still optimal: refer to the upstream documentation and focus on explaining the Fedora-specific stuff.

And it would be very rewarding if we had a list of the most frequently asked questions and could include the solutions found in Quick Docs.

Maybe we could include a special FAQ page in Quick Docs where we dynamically include the last 10 or the most important questions with a link to the corresponding QD article.

1 Like

Thanks for sharing your thoughts. :pray:

My suggestion in this thread starts from gaps I noticed between solutions accepted in Ask Fedora and repeat questions on related issues posted in Ask Fedora.

To be fair, it is not really about visibility of solutions in Ask Fedora and put links in Quick Docs.
Many issues posted in Ask Fedora are not Fedora specific.

I want to consider a new category ‘Audio’ and invite writers across working groups and SIGs. That’s why I opened a poll until end of February and test the idea with Music & Audio SIGs. I believe the main benefit of rewriting Ask Fedora solutions is our super helpers in Ask Fedora don’t get the same questions over and over again.

In audio issues, it is impractical for users to read upstream documentation and learn how to troubleshoot. I spent days to check entire upstream docs about all audios; Pipewire, wireplumber, JACK, Linux kernel, and known issues in bugzilla (hardware specific).

I refer to Arch WIki for audio issues, but don’t know when I really need to edit config file. For new users, editing config file for ‘plug and play’ features in other OSes seems to make confirmation bias ‘Linux is hard’ even worse.

Pipewire is actually a media server, and Wireplumber is the configurator so to speak.

There is, or was such a place. You used to be able to create an issue against it on Pagure, but I don’t know the state (of it) at this time.

Well, if I summarize this thread so far, we are obviously short or information about audio and video. And we have a proposal how to fill the gap.

On the other had we have some inforamations:

  1. There is one very short article in Quick Docs: Installing plugins for playing movies and music :: Fedora Docs

  2. We have issue Issue #133: Adding (Debugging) info to Navigation tool - quick-docs - Pagure.io and some links to WIKI pages, which should get transferred to Docs.

Probably we should check how far we get with this.

1 Like

Thanks for reminding us of wiki pages on sound, pulse-audio and sound troubleshooting.

I checked the pages on sound troubleshooting, which are largely not up to date and most of actions/commands there are no longer required. Any wiki pages on sound issues written before F34 in 2021 (Pipewire became a default media server) need to be checked for relevance.

So, we still need to filter top solutions on the topic in Ask Fedora.

Compared with audio issues related to sound card (plus other external devices and pro audio equipment), media server and Pipewire sub packages, I reckon plugins and codec issues have different troubleshooting paths.

Plug-ins and codec pages require reviews independently of audio issues (a category on its own).

If I oversimplify two categories,

  • Plug-ins and codec: resolved by installing additional packages. Debugging not usually required.
  • Audio issues: multiple levels of issue identification required (hardware, configuration) and understanding on Pipewire. You need to run debugging in some cases.
1 Like

You’re right. My proposal is to create a chapter on audio (not video, which is another big topic on its own) as pilot within Quick Docs. I guess you’re supportive of this, right? Fedora is upstream of many audio related packages, so we could raise awareness to super helpers in Ask Fedora, SIG members and packagers as well. Thank you

This initiative will require more time and co-authors to write up a draft for the Magazine. Please check the article proposal below and hands-up if you want to co-author the Magazine article with me. Thanks.

To kick-start this initiative relatively light-weight and standalone, I’d like to write an introductory Quick Docs article on Linux audio and audio settings that will touch upon many posts and solutions in Ask Fedora. I can just tag ‘audio’ and ‘how-to’ in Docs metadata header. This way, I can publish articles quickly without getting stuck in discussion.

Introductory article (self-assigned to me)

  • Linux audio architecture and Pipewire / key concepts: A rough draft uploaded to Matrix Chat Etherpad in Music & Audio SIG
  • How to run video conference and check audio settings
    – end to end workflow: audio settings in desktop environment and applications
    – common causes of ‘no audio’ issues: device not detected. no audio on recording
    – hum noise

Afterwards, we can expand this to other articles and promote the idea in the Magazine.

New articles

  • Issues
  • How to guides
    How to debug sound problems: Wiki conversion required
    – Set up external device and interface
    – Optimize audio settings for better audio capture / quality
    … more

Yes, I am!

And I’m wondering that Fedora is upstream of many audio related packages. I remember a lot of critique that Fedora misses a lot of widespread codecs because of potential legal issues. This would make Fedora unusable for audio purpose, at least without third party software to compensate the lack of codecs.