Slashdot Mirror
Free & Non-Free Documentation
Guylhem writes "After the problems the LDP had with Debian rules, it seems clear we need an organization which would for example sort documentation between free (as "libre" or "freedom") and non free. After some discussions with people from the GNU project and the FSF, we came to the conclusion no such project already existed. I am please to announce that I am now starting the GNU Writing Movement with help from the GNU project. We will provide links to existing free documents, with a possibility to rate the documentation quality.
The project is not competing with existing documentation project such as the LDP or GDP. It will complement them, both by serving somewhat as a meta-project for free software documentation, to provide help to authors willing to replace their FAQ or HOWTO will a full Guide on a specific topic, and to develop brand-new book-length material on many topics.
"
If you can't find a home for your documentation at an existing documentation project, and you agree with the philosophy of the GNU project, we can help you. Volunteers are welcome for the first phase of the project - cataloging existing free software documentation, rating it, and determining TODO lists for what needs to be documented.
I think what really may be needed is for an organization, such as this one, to raise donations to hire writers to fill in the gaps in open documentation. We all know some projects are documented well others poorly, all of them could use help making the documentation make sense to newbies. This just isn't something that enough people do out of the good of their hearts. Maybe this would be a path to getting quality documentation.
Spencer Ogden
I remember when people said the software was gonna be free, it was thru support and documentation that they were gonna make money.
Now the documentation is going into the GNU-virus? How are people around the computer field supposed to make money?
If, on the other hand, you are trying to de-legitimize Linux as an economic activity, making it an artistic activity instead, this isn't the way to go about it. You need guns for that.
People have to make money (in this society) when they spend a lot of time and resources in something. Otherwise they starve or they lose sleep or other needed resources. They will fight for this availability to make money, no matter what.
Goat sex free since 2001
Free OS, free code, and now free support... i am wondering if some of our best brains are going to have to (in the future) put their open source projects on the back burner so that they can earn enough to make rent.
Not knocking GNU or opensource mind you. Just pointing out that geeks like toys as well as the next guy. Toys cost.
"...after all, we are not communists." ~ The Godfather
So many man pages out there are absolutely useless they are detrimental to read. Every single man page in existence should have at the least several accurate descriptions of the command's common usage.
For example, after showing the various flags to throw for "grep", why not then show some common examples using those flags as in: grep -i help your_file.txt? That would do wonders for people trying to learn the common commands and I have necer been able to figure out why this is not a common feature of man pages. Fix the basics first, then worry about how free some piece of documentation is and composing "book quality" documentation.
Oh! An opportunity for someone to make a living doing Open Source (writing books about Open Source): SLAM!!!
OK, the arguement is, noone is preventing the publising of books, merely creating an alternate channel. You are creating competition for these materials, which will hurt their bottom line. True, the best will win out, and, if a publisher provides a more desirable product, they will win.
However, based on some of the Microsoft-bashing that goes on, it will only be a matter of time before people are questioning if people are buying, say, O'Reilly books due to FUD. Also, some might just say, if it ain't an open standard, I don't even want to talk about it.
I wish people would renember how many time's we've all been screwed over by someone who seeminly out of generosity makes something free, or very easy to distribute - and then when we really need it they ream the screws to us like there's no tommorow. I can't see how anybody could blame Debian for wanting to be proactive just this once.
Maybe what is needed is a wikipedia for documentation. Usually programmers are not very good at documentation, and users find difficult to get into docbook and stuff.
Wikipedia have got about 20000 articles in just one year, some of them of very good quality.
If we were to give users the ability to do the documentation themselves, I bet they would use the oportunity.
The teaching from wikipedia is that you get good quality writing if enough people works on it. Something like code peer review.
When his defense asked, "Which computer has Jon Johansen trespassed upon?" the answer was: "His own."
Alas, I'm not the one who decices. No I didn't wake up someday and said to myself "let's use a non free license to piss off debian people". We had a license. We decided to use it. Then we had a problem - I'm just doing my best to work around it.
:-) I didn't make it up. It is really a problem. Debian was going to move most of the LDP documents out of its main tree. We did everything in a hurry and it's now (mostly) fixed. But *prevention* is better - I'd rather have avoided this problem altogether!
Here we have a license problem (you read the Debian story did you? Hmm? Yes I know that's slashdot
In the imaginary problem you present, rewriting all the manpages doesn't sound like a good solution. It would also be counterproductive since most of them are available under a free license.
Which aren't? There you will need the GWM. We will be able to tell precisely which document is not free (free={GPL,FDL,BSD,OPL...}) and then we can rewrite that very document.
The bad solution is forgetting the license problem until it finds you.
I was watching the news a few years ago and some guy in India had lit himself on fire to protest the Miss Universe pageant. Sorry bastard, didn't know the difference between a worth cause and a silly one.
Surely the fate of the Brazilian dung beetle is more important than this cause. Let's leave the definition of "free" and Free documentation to a later generation who will hopefully have realized what a ridiculous topic this is...
Alas, the OSWG died of a slow and painful death - here's the death certificate BTW : http://www.oswg.org/.
The LDP is just about writing documentation. If you add the BSD doc proj., the GNOME doc. proj and the KDE doc proj you have 99% of the documentation that's currently produced.
The OSWG did try to become a meta-documentation project. It failed. Too bad. But we still need some kind of organisation around the documentation projects, for exemple to sponsor authors, decide common documentation formats or rewrite non-free or bad documentation, etc.
Just consider the free software world and the number of organisations (LPI, GNU, Open something) which try to support individual projects.
Now consider the free documentation world, where there is *only* 4 significant projects, and no meta organisation *at all*.
It's not about fragmentation or waisting effort- it's the beggining of a collaborative work. If the LDP, the GDP, the LDP and BSD doc. want to build bridges, we (GWM) will be there to help them. If they don't, we will still collect documentation and try to combine the fruit of they effort.
That's the beauty of free software - you can build on someone else's work.
I'm curious. Is there something in particular about the licensing terms that Debian would like to impose that bothers you? What do you mean when you say their "ideological purity is going too far"? Or are you simply finding it annoying and burdensome that they would do this post facto?
--Lawrence Lessig for Congress!
Whomever writes the code should document it. Anyone else will likely produce something that is inadequate. Only the developer who wrote the code truely understands the work right down to it's semicolons. Developers always think there code is very self explainatory but trust me when I tell you that other developers are not interested in looking at your code. This is because it's either crappy code or it's potentially nicer than something they would write but the most likely scenario is that the just want to know how to use it and move on with their own code.
;-P
Please do not obsess over organization and presentation. Users will only withstand a very basic hierarchial organzation. Just start vi, insert the standard <html> boiler plate, and start typeing. Use lots of contextual inline hyperlinks to sections of LXR'd code, hyerlinked specs, other topic documents, and related sites. Don't make people dig for this stuff. Yes, lead them by the hand. Only the largest projects need a full blown index. Have one page of intro and a page for each topic. If you introduce a new major feature or there's an issue just write up a page of html on it and add a link to it in the main page. Use lot's of lists and tables. They provide good landmarks and organize info nicely.
Most importantly just get the information out of your head so people can use it. Spending one day a week on writing up a page on some topic will do wonders for your project. There are three reasons for this. The first is simply that users will know how to use your code which is obviously a prerequasite to actually using it. Second you will understand your code better and likey become keener to it's strengths and faults in the process. If you find yourself evading a particular topic then that's the topic you should explore. Don't leave that neusance dangling over your shoulder or it will take the fun out of your work. And it might very well be an artifact of an issue with the code or application. Third, colleagues and users will ask fewer questions and be able to contribute intellegently to the discussions and sumit useful problem reports.
Documentation is so very important, your code is virtually useless to anyone except you if you don't. Finally, if you spell as well as I do, use a spell checker
They just decided to put the documents that don't meat DFSG in a non-free directory. It's not a big deal.
Slashdot is making a big deal out of this perhaps... And btw a lot of mis-informed comments like
this one and were moderated up last time so don't believe everything you read here.
There are only 273 LDP documents that don't meet Debian Free Software Guidelines. A lot of the authors of these articles probably don't care too much if people translate their documents or if people add things to make them distro specific etc. However, unless the author gives specific permision then it is illegal for Debian to do so.
Seriously though, as I look down the actual list of non-free documents I have a hard time seeing what the big deal is. Many of them don't really apply to Linux these days. Some dealt with old versions of X, the 2.2 kernel, old versions of red hat, old hardware, or integrating Linux and OS/2 for example etc. Some of them are amusing and have historical value like the coffee-howto. I was surprised that the apache-faq was non-free but that's about it. It's easy to forget how fast things change in the Linux world, reading through the list reminded me of that.
Conclusion: 1) Don't believe everything people say on slashdot. 2) Most people are happy with licenses like FDL or other free licenses so please consider using one. 3) If you don't use one Debian doesn't hate you, they'll just put your document in the non-free directory.
btw: If you want to know whether your LDP document does not meet DFSG just check this list. I really doubt your document is on it.
Documentation has since gotten better with innovations like the LDP, enabling developers and writers to submit and critique documentation but the fact of the matter is, we still need to concentrate on getting useful, readable, concise and comphrensive documentation on individual components. It still is hard to find the latest PCMCIA setup instructions.
I am not sure that fighting over what is free & non-free is necessarily the best thing. Although it is great to see the latest FreeBSD and Linux book sets at Barnes and Noble and Amazon - I think the community still has a ways to go in developing "useable" documentation. What are your thoughts?
-Pat
Now we have three open-source/free software doc projects: The featured project, LDP, and OSWG.
Open source and free software are not the same thing. They are very similar, but they do in fact have different points of view and differing objectives. Licenses are one of the more powerful tools these organizations can use to advance thier position.
Your point seems to be that you don't really care about all this balony, you just want the documentation. If that's all you care about, then these organizations are truly redundant. But there's more to it than that.From the preamble of the GNU Free Documentation License:
The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
To some people, these things matter - a lot. There are issues to consider besides just making the documentation "available". Like ensuring that it will remain available. It makes perfect sense that groups would organize in support of these principles.
--Lawrence Lessig for Congress!