Google Is Launching "Season of Docs" To Help Improve Open-Source Documentation

[OlafLostViking]

I am just setting up a Prosody server and realized how improvable the documentation coming from the project itself is for newcomers (or at least me), when you want to set up a "good" XMPP service. Just a quite minimal introduction and a non-sorted list of modules (sometimes with only the module name as "documentation"). Some important ones are available only as community module. The Debian backports also contain only parts of the modules available. No real overview or step-by-step howtos. I'm collecting needed settings from blog entries and guessing. If anybody here knows about a good howto with explanations, it would be very nice if you could post it in here :-)

[coder]

No documentation method or system do help when developers will not tell everything. You need to read existing code and from implementation sources what some API really does.

I completely disagree with involving outside authors, in this scenario. An API must be documented by its original authors. Someone coming along, after the fact, cannot reliably distinguish implementation bugs from original intent. And once documented, a behavior becomes virtually set-in-stone, making it very difficult to change - even if the documented behavior is a bug and problematic.

The kind of documentation it makes sense for them to write are things like intros, tutorials, conceptual overviews, translations, trouble-shooting guides, etc. Maybe they could flesh out the core API docs with some examples, as well as some spelling and grammatical fixes.

The only way I'd have anyone else writing API docs would be if you could really get the original developer(s) to carefully proof-read the resulting docs. Even then, it's not ideal. The ideal way to document an API is before & during implementation. Afterwards, even the original authors might have trouble recalling their intent, in a few places.

[skeevy420]

The open source world works this way:

https://www.debian.org/

->https://www.spi-inc.org/
->https://www.spi-inc.org/projects/x.org/

I did a search of the word "linux" at the AMD Knowledge Base. I'll sum it up.

17 results: 12 are various AMDGPU-Pro install guides, two are LunarG install guides, one is about enabling FreeSync, one about installing Catalyst headless for Cent OS, one about ROCm for a FirePro.

"xorg & x.org" : both 0 results
"mesa": 1 result and is one of the AMDGPU-Pro install guides above
"kernel": 4 results, more of the same AMDGPU-Pro guides
"environment variable": 7 results, 5 of the same guides and the 2 LunarG guides
"AMD_DEBUG": 0 results
"R600_DEBUG": 0 results

Like I said before, Phoronix is a better source of information on AMD GPUs than AMD themselves. I love my AMD cards. I do not love how all the documentation is scattered everywhere and how not even AMD has links to it all.

[schmidtbag]

The Alsa documentation is good enough, I found my .asoundrc somewhere. With the loopback driver you can record desktop audio. Check your audio devices with the command aplay -l and set the default audio output device number

Maybe it's good enough today; like I said, it's been a while since I looked at it, but a couple years ago the vast majority of it was useless. ALSA's documentation is good enough for relatively simple things, such as doing nothing but a loopback driver. But it becomes increasingly more cumbersome as you add more functionality or are handling multiple output channels.
Meanwhile in PA, you don't have to configure anything - you can just run pavucontrol and use that to assign the audio input source (which can be any output source).

Pulseaudio is typical IBM garbage software. IBM software reinvents the wheel with poor results.

If you actually knew what it did then you'd know it isn't reinventing anything. PA isn't a replacement to ALSA, seeing as it depends on it.

[skeevy420]

You are comparing to macos, android or windows. Every user knows how hard is to solve technical problems in those systems. You can not do much. Windows users install the OS again or other hardware to solve problems. AMD open source documentation for end users do exists now:
Amdgpu kernel doc: https://dri.freedesktop.org/docs/drm/gpu/amdgpu.html
Xorg doc: man amdgpu: https://www.mankier.com/4/amdgpu

There is even a distribution for AMD graphics. https://www.youtube.com/watch?v=fKJ-IatUfis

And very little if any of that is hosted by AMD. Some regular end user would have to know what Mesa was, what modules were, either the proper terms to Google or the proper commands to enter in a terminal, and likely more to use any of that. People like you and I can use that information, someone like my Mom couldn't...at least not how any of it is written in their current forms. I say all of that as someone who painfully learned a lot of stuff sifting through man pages -- it shouldn't be that hard and difficult to find the right information and the next generation of users shouldn't have to suffer like we all did.

Like I said, I wasn't trying to rag hard on AMD since it's a problem that effects all Linux users for a lot of hardware and software as well as it wouldn't be on AMD to provide some of that information since Ubuntu, Suse, Manjaro, Debian, and Fedora might do certain things differently from one to another...but a noob-level general overview and links to relevant distribution documentation would be nice.

On projects like AMDGPU that consist of multiple components, it just kind of sucks having to go to each component and read their write up that may or may not have the information one needs. Ever try looking up AMD_DEBUG stuff? I come across Phoronix threads more than I do actual documentation. I learned about R600_TEX_ANSIO here. The EQAA env variable documentation is sorely lacking...I had to read the damn source code to figure it out...and, yes, you're more likely to come across a Phoronix post or article when looking up EQAA too. IMHO, Phoronix is 50% of AMDs documentation on AMDGPU . Thanks for sifting through mailing lists and commit histories Michael .

Ideally, AMD, no, "Random Company or Project" would have great write-ups that covered both end users and developers and then the various distribution guides could adapt the RCoP documentation to fit how they do things.

[Bsdisbetter]

That's actually a brilliant idea. Sorely needed. Some projects are severely lacking.

Some? Most.

I know that a lot of y'all here are developers and that's where your focus is, but, as an end user, manpages and READMEs and whatnot are just as bad IMHO. Some are overly technical, some have vague examples, some aren't technical enough, relevant information is scattered among different sources.

Software is as good as it's useful. For end users, different kind of documentation is needed. What you're saying is (also) bad structuring of documentation. README should target software users, and if software is application, then it should target end users, and provide relevant information for end users,..

Also, quality aspects are needed, like works out of the box, stability, performance,...

[OMTDesign]

Goo to see that this is initiate is being offered internationally, just like their Summer of Code. I wonder what projects Google is eyeing, other than Qt, for manual pages?

[NotMine999]

Great idea ... in theory.

Sadly Google has a bad track record of dropping projects. I hear that there is even a web site that documents that fact, but I have not bothered to look it up.

Most FOSS developers that I have encountered over the years either: (1) don't get paid to write "proper documentation"; or, (2) do not have time between R/L and coding to write the necessary documentation of their code; or, (3) seem to have no desire to write documentation, preferring to fallback on bug report tools like Github and Sourceforge to document their code.

[schmidtbag]

I know that a lot of y'all here are developers and that's where your focus is, but, as an end user, manpages and READMEs and whatnot are just as bad IMHO. Some are overly technical, some have vague examples, some aren't technical enough, relevant information is scattered among different sources.

Like, as a Linux user, I've learned more about how to setup my AMD GPUs from random Google searches, Arch Wiki/Gentoo Handbook, and Phoronix threads than I have from AMD. AMD's Linux information straight up sucks due to how scattered about all of it is and how generic their official information is. There should at least be some pages on an xorg.conf showing my xorg.conf (it contains the current defaults) and what the containing values do, a second xorg.conf showing a multi-montior setup,and a multi-monitor, multi-gpu setup; an advanced setup page with AMD_DEBUG and other environment variables; another advanced page about overclocking.

I know what you mean, except replace GPUs with ALSA. I'm sure PulseAudio wouldn't be so wide-spread if ALSA's documentation wasn't so... useless. Like it's not even a matter of being difficult or incomplete, some of it is just simply outdated and wrong. However, it's been a few years since I've really taken a look at ALSA's documentation so maybe it got better, but at this point I have no reason to ditch PA.

I guess another way of looking at things is if you don't have a decent GUI tool to use something, you need comprehensive documentation to take its place. Many programs in Linux have neither, so, I hope this project of Google's becomes a success and comes back for another season.