PDA

View Full Version : Treating bad documentation or ugliness as a bug?



Altarbo
August 20th, 2007, 12:32 PM
This is something I've been thinking about recently:

Since I've started using Linux about three months ago, I've noticed that very often the documentation for many things is bad or absent. One solution I've thought about is to distribute a version of Linux (Debian or Ubuntu at the core so there aren't incompatibilities) with third party documentation (not written or necessarily even approved by the software authors). There would a wikipedia-esque site where users could contribute tutorials on how to accomplish tasks; general information pages about pieces of software as well as formats, protocols, developers, licenses, etc.; and manual pages.

You would have to register an account under your real name and nonregistered users would not be allowed to contribute. Versions of each individual work could be tagged as having been officially accepted by the software author, having passed peer-review for grammar, having passed peer-review for accuracy, having passed peer-review for clarity, and possibly others. If important aspect of desktop Linux were not covered, users could file bug reports, and a list of documentation that needs to be written or improved would develop. All contributions would be released under an OSI approved (FLOSS), GPL-edible license. Looking through the FLOSS licenses so far,I haven't seen one that I really like. I'm still looking; don't want to add another license for no reason. But I'm thinking about modifying the NCSA license's wording so that it makes more sense for written, but not compiled work; and removing the clauses.(see attachment) The idea being to make documentation that any software authors, maintainers, or distributors from upstream could pick up the documentation and use it for their work.

Less organized are my thoughts about the graphical aspect. There should be a way for people to report a gtk theme that doesn't have matching themes for qt and windowmaker. I'm not much a graphical artist, so any input on what kind of environment would foster collaboration in the name of good looks, would be appreciated.

My question is are there people out there, who would be interested in contributing to something like this, who otherwise wouldn't have a desire to contribute any documentation? Are there people out there writing documentation who would be willing to share it with a project like this? Is anyone already trying this? Even if you think it's a horrible idea, I'll appreciate any thought you have on it.

popch
August 20th, 2007, 03:00 PM
Seeing how many software authors do not appear to have a clue what belongs in a user documentation, I think having some sort of 'standard' for user documentations would be great as a start.

@trophy
August 20th, 2007, 03:24 PM
"... and *my* axe!!!"

Seriously, though... set the thing up and I'll register. I am almost done with Deathly Hallows anyway, and I'll need something to do soon.

macogw
August 20th, 2007, 08:12 PM
Wikipedia uses the GNU Free Documentation License. Why not use that?