I wrote already in the past of my «doc fetish» in the past, but as you know this is one of the themes that continue proposing itself every few times. In this case, today I decided to update the maintainers’ guides for xine (with the 1.1.4 release changes), Amarok (with the Mongrel change) and ALSA (with the changes introduced in 1.0.14_rc2, as well as documenting the midi useflag introduction and a proper way to fix the programs that require alsa-lib built with midi useflag enabled).
I’ve also decided to send to the GDP team (read: nightmorph) a series of bugs with tasks to update the ALSA guide with more updated information, as there are quite a few changes in the way ALSA was handled in the past months, as well as references to TiMidity++ that needs to be cleared up.
Unfortunately, I really suck when it comes to writing user-oriented documentation, so I ended up giving them/him a task that is far from being easy to accomplish: documenting alsa-plugins package usage in real-life situations. I will point out some more information to nightmorph but I’m not sure if he’ll be able to handle that by himself.
One of the use of alsa-plugins is to use it with PulseAudio, too, and that would belong to a proper PulseAudio guide, that does not exist right now. Just asking for one won’t work, as if someone in GDP was already using it, there would have been one already, and as I said, I suck at writing user-oriented documentation so I can’t really contribute one myself.
So, what is this entry all about? Well, it’s a request for help to all our users: please help us make Gentoo a more friendly distribution, in a way that actually work without disrupting the current development process (that in general works well for most of the developers): providing documentation. One of the great things about Gentoo was that GDP covered a lot of different topics, from ALSA to Bluetooth, from LVM to home routing, but now that the team seems more or less restricted to nightmorph, it’s impossible to provide enough good documentation, it’s already a difficult task to keep updated the documentation that is available.
If you feel like writing documentation you don’t even need to know the GuideXML format used for writing it: you just need to submit the text in your preferred format (plain text possibly, I’m not sure how they’d like ODT or LaTeX, but they might accept that too), and they’ll take care of the needed conversion.
