Fedora Multimedia Documentation: Provide a unified place in Quick Docs / dedicated site for docs related to third party codecs, hardware drivers, etc. #58
Labels
No labels
Contributors' Guidance
Improve written Material
Contributors' Guidance
technical support measures
effort
high
effort
low
effort
medium
good first issue
help wanted
meeting topic
needs changes
needs reporter feedback
needs review
priority
high
priority
low
priority
medium
priority
on hold
type/content
type/misc
No milestone
No project
No assignees
4 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
docs/tickets#58
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
This is an idea to improve the user experience in Fedora Docs.
Currently, Fedora Documentation regarding third-party software (particularly software such as patent-encumbered codecs, hardware drivers and hardware-accelerated codecs) is scattered throughout Fedora Docs.
There are dedicated sections for RPM Fusion in: Fedora Quick Docs; Fedora Atomic Desktops; Fedora IoT; Fedora Gaming.
The most complete of them being Quick Docs. The sections in other parts of Fedora Docs either copy Quick Docs, link to it, or provide inaccurate / outdated information on how to set up RPM Fusion (such is the case with Fedora IoT).
Because of this, new and even experienced users that encounter Fedora often end up not having a great experience with the distribution (the same piece of information being present in multiple places, and sometimes looking slightly different from each other) and move on because they do not know what to trust. Or they end up loading a random script from the internet that sets up all of it and more.
This is a suggestion to transfer all documentation related to multimedia in Fedora (specifically codecs, drivers and repositories such as but not limited to RPM Fusion) into its own section of Fedora Documentation. This would allow for pages that use software related to multimedia to link to a single source of truth instead of having duplicate (and sometimes outdated) information, as well as for contributors to not duplicate work across Fedora Docs.
I am willing to work on this with guidance @rathann
Note: pictures attached to illustrate the problem
Hi @qvest, thanks for kicking off the task planning in the ticket. As a note, this is related to #50 for the Multimedia collaboration. The shape of the collaboration is still taking shape, but I think we can start cataloguing and organizing the content now.
I think what we have loosely agreed to in #50 is creating a new docs site, something like
docs.fedoraproject.org/en-US/multimedia/or something similar. The main goal for the Docs Team is to reduce the sprawl and duplicity of documentation related to installing multimedia drivers, codecs, and other media enablement things. There might be more ambitious goals to think about, but the top priority for the Docs Team is giving this content we already have into a better home. We also want to help get things set up with the Multimedia SIG and make sure this is integrated in a way that is easy for them to maintain.Could you start by cataloguing all of the existing docs which detail multimedia usage, including but not limited to RPM Fusion content, in the Quick Docs site? What would be helpful to know is a list of all the pages on Quick Docs which are candidates for moving to this new Multimedia site. Then, we can start mapping out a plan for how to tackle the move in a coordinated way, so that things like links don't break after URLs change.
@qvest Assigning to you for taking the lead on the initial cataloguing of the existing content. 📝
Hey, I've managed to catalog everything under Quick Docs that was about codecs, drivers, etc.
However, things like flatpak, appimage and snap bundle codecs together with the installed application, so I also added those to the catalog.
I also added compilation from source since some programs might need it to be installed in an upstream-supported way (for example: the mpv media player is only supported officially trough compilation from source). Although, the program in this example is also available on flathub and directly from fedora as well.
I added language package managers as well, since some other programs can also be installed that way (example: yt-dlp from pip (I think the yt-dlp package from pip also installs codecs? I am not sure))
I did not add things like podman or docker since those are most likely beyond the scope.
Mentions third-party software directly
Adding and managing software > Finding and installing Linux applications > GNOME Software > Manage repositories (mentions Flathub)
Adding and managing software > Finding and installing Linux applications > KDE Discover > Manage repositories (mentions Flathub)
Adding and managing software > Finding and installing Linux applications > More information (mentions Flathub)
Adding and managing software > Third Party Software > What is third-party software > Installation methods (mentions RPM Fusion, Copr, Flatpak, Snap, AppImage, Language package managers, compilation from source, direct binary downloads)
Adding and managing software > Third Party Software > Using third-party software safely > Understand dependencies (mentions Flatpak, Snap)
Adding and managing software > Third Party Software > Using third-party software safely > Use third-party repositories wisely (mentions RPM Fusion)
Adding and managing software > Third Party Software > Common third-party sources (mentions RPM Fusion, Flathub, Snap Store, AppImage, etc.)
Adding and managing software > Third Party Software > Enabling the RPM Fusion repositories (provides a step-by-step guide on how to enable RPM Fusion on every type of Fedora system)
Adding and managing software > Third Party Software > Flathub (mentions Flathub)
Adding and managing software > Third Party Software > Snap Store (mentions Snap Store)
Adding and managing software > Third Party Software > AppImage (mentions AppImage and third party repositories for this format)
Adding and managing software > Third Party Software > Installing Software from Source (mentions building packages directly from source code)
Adding and managing software > Third Party Software > Language package managers (mentions installing software from places such as pip, npm, etc.)
Adding and managing software > Installing popular applications > Installing plugins for playing movies and music (mentions codecs and RPM Fusion)
Adding and managing software > Installing popular applications > Installing Chromium or Google Chrome browsers (mentions RPM Fusion and third-party repositories)
Adding and managing software > Installing popular applications > Installing Spotify on Fedora (mentions Flathub, snapcraft / Snap Store, RPM Fusion)
Usage and customisation > How to Set NVIDIA as Primary GPU on Optimus-based Laptops (mentions RPM Fusion)
Mentions or links to a place where third-party software is talked about
Adding and managing software > Package management system > Finding software (mentions third-party repositories)
Adding and managing software > Finding and installing Linux applications (mentions third-party software)
Loosely related to Multimedia
Getting Started with Fedora > Music & audio (mentions sound card support and ability to play music CDs)
@qvest Many thanks for the input. It’s impressive just how wide-ranging the information is.
I think we need to develop a strategy for how we can improve this. I think we all agree that Quick Docs should be the authoritative source.
The first step, therefore, should be to improve the information in Quick Docs.
Once that has been done, at least in essence, we should contact Fedora Atomic, Fedora IoT, etc., asking them to link to Quick Docs for the basic information and then simply add points that are specific to the edition or spin.
A completely different issue is flatpack and similar external sources. We have basically no influence on these. I’m inclined to put that on hold for the time being and come back to it once the first two steps have been dealt with.
@pboy I thought part of the idea of #50 was to split out the content into its own dedicated site. Is there a good reason to keep it in Quick Docs?
On another note: we need to coordinate this tickets (and related ones here) with the tickets created in the QuickDocs repository.
Perhaps we should set up a project at the org level called ‘System-wide improvement of multimedia documentation’ (or something shorter). There, we can reference and manage/track tickets from both (and possibly other) repositories.
Well, this concerns Quick Docs directly, too. We should maintain a reference there and keep an eye on the documentation texts there (in Quick Docs). After all, it’s not just about the multimedia information, but also, for example, the metadata. Or the tracking of timeliness.
@pboy wrote in #58 (comment):
If you're referring to Atomic Desktops, there's not much to document about multimedia in general. We recommend using Flatpaks from Flathub, which contain the necessary codecs. It's likely that the same recommendation will be made for other desktop editions at some point.
Documenting driver installation (i.e., NVIDIA) for Atomic systems was discussed in a BoF session during Flock. I would suggest that these docs land in the Atomic organisation. We have a dedicated community-maintained container build examples repo which already contains a CentOS Stream example for NVIDIA.
I agree with @jflory7. I feel like if this sort of documentation is to be improved, it should have a dedicated place to improve in. Having it in Quick Docs sounds like a good idea at first, until a first time Fedora user goes to the docs to try and figure out why videos on Firefox aren't working.
They are met with a lot of documentation to look through. And the information they actually need is buried under Quick Docs > Adding and managing software > Installing popular applications > Installing plugins for playing movies and music.
Having it on the first page of the Docs would help such users that don't want to go too far down the docs rabbit hole. It would also help clean Quick Docs up and still have it available for general tutorials from Fedora users that go into detail on things other than multimedia (that may or may not include podman / docker, language package managers, compilation from source).
Another suggestion, trying to reach a middle ground: Multimedia stuff could remain in Quick Docs, but instead of duplicating tutorials, reference those in the dedicated Multimedia section on the first page of Docs.
Another another suggestion: Multimedia stuff remains in Quick Docs, but instead of separating into "RPM Fusion", "Plugins for movies and music", etc. have those in a dedicated "Multimedia" subpage in Quick Docs. That would be home to dedicated subpages / categories: "RPM Fusion", "Plugins for movies and music", "Installing Spotify", "Installing Chromium or Google Chrome".
Though, I'm realizing now that "Multimedia" as an umbrella term sounds too vague. Is a web browser related to multimedia? In technical terms it is... should we have used "Hardware-enablement" or something similar instead to keep it strictly about codecs, hardware drivers and such?