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

[phoronix]

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

Google's Summer of Code is embarking on its 14th year of encouraging student developers to get involved with open-source development. Complementary to code contributions, Google is preparing its inaugural "Season of Docs" to help technical writers get involved in better preparing open-source program documentation...

http://www.phoronix.com/scan.php?page=news_item&px=Google-Season-Of-Docs

[milkylainen]

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

[Mike Frett]

I wouldn't trust Google to clean my toilet. They'd get half way through and then quit.

[carewolf]

Qt is probably the project that needs this the least. But I guess even good documentation can get better.

[Weasel]

So doxygen is not enough? No way... /s

[schmidtbag]

So much negativity... I personally think this is a great idea. Even if nothing gets complete or they can't tackle anything too huge and complex, some documentation is better than none.

[Guest]

So much negativity... I personally think this is a great idea. Even if nothing gets complete or they can't tackle anything too huge and complex, some documentation is better than none.

Yep. Software (library) is as good as it's useful.

Even, if library is brilliant, without API documentation it is hard to use. And, worse libraries with documentation take over, just because other developers know how to use them.

[skeevy420]

Yep. Software (library) is as good as it's useful.

Even, if library is brilliant, without API documentation it is hard to use. And, worse libraries with documentation take over, just because other developers know how to use them.

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.

If I wasn't a more technical user I know that I'd have one hell of a time trying to use my AMD cards and that having a 260x, requiring me to use the CIK stuff to use AMDGPU, assisted me by forcing me to have to do it all the technical way and to try things in multiple ways before calling something a bug since it was "experimental". If I were a non-technical user and just bought a 580 never using my 260x or any other previous AMD card, I'd think the 580 was crappy due to all the tearing and vsync issues inherent in Linux and not the card itself.

I'm not trying too be hard on AMD because it's both them and distributions. It's not like every distribution has good documentation on all of that for Intel or Nvidia and not all users will trust a random Phoronix post or are able to use the Arch Wiki to fix a Suse problem.

[Jabberwocky]

A large part of Docker's success has been the project's documentation (not just source code). I have not found any project that even rivals it in this regard: https://github.com/docker/docker.github.io They have kept it simple by using built in language documentation and markdown. Seems to be working well for them so far.

Libraries are another story though.

[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.