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
Writing documentation is an incredibly difficult task, and few people do it well; to throw out an incredibly useful and well-written resource simply because of a miniscule licencing technicality is both horribly naïve and terribly anal behaviour. How does this guy think he'll be able to rewrite, say, all the Linux man pages without (a) having the original manpages as a reference and (b) quite possibly not being anywhere near as good a documentor as the original Linux Documentation Project? Open-source documentation is scarce and hard to come by as it is, why does Debian feel the need to exacerbate this shortcoming even further?
Loneliness is a power that we possess to give or take away forever
Perhaps I don't understand the pure joy of releasing information with 1000 conflicting licenses. If I were to write documentation for an existing software project, I would simply contribute it to the original author, so it may be released with the distribution, under the same license as the software.
Does my naivete in this matter mean that the author will exploit my contribution to the project, and use it in a way that I didn't intend? Who cares? If the software is "less free" than the documentation, isn't that a problem anyway? And if the software is "more free" than the documentation, isn't that just dumb?
Man, some people are just looking for a fight.
My Freakin Blog
No, this isn't a troll, just an expression of frustration from someone who simply sees the fragmentation of open-source/free software as a Very Bad Thing. Those who promote this type of behavior (including the submitter) are doing a disservice to the open-source/free software community, as well as throwing up unnecessary barriers to those who would like to be part of the action but simply do not have the time or the patience to deal with all the in-fighting.
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
If this project becomes a centralized point of distribution or access (ie: SourceForge,) this could really help the open-knowledge community.
For example, many people run out to buy expensive assembler books when the best resource is available online. Or, they run out to buy expensive Linux device driver manuals when the best resource is available online.
Open-source software mainly helps people write new software that uses key techniques / algorithms from open software. Open-source documentation, on the other hand, helps impart the foundations on which the open-source programs get created.
Ideally, this openscience approach would spread -- and students wouldn't need to spend $500 per semester on textbooks. And unfortunately, the Project Gutenberg idea to import books as their copyright expires (50 years after the author dies) would never fly for technology-based books.
As a side note, this index of online books has a lot of good information.
It all goes downhill from first post
As an author, I'm offended by your suggestion that the LDP, and by inference the authors of various documents, had "problems" with the Debian license.
It's the other way around. Debian manufactured a crisis and is trying to put the blame on the volunteer authors instead of accepting that their quest for ideological purity is going too far. If Debian has a problem with one of my documents, they're free to rewrite it from scratch. Paraphrasing is *not* sufficient.
For every complex problem there is an answer that is clear, simple, and wrong. -- H L Mencken
Mandrake Linux manuals:e word.html#LEGAL
http://www.mandrake.com/en/doc/81/en/ref.html/for
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation[...]
Despite some whiny comments below, this meta-project sounds useful and appropriate to me. I'd encourage serious contributors to give some attention to the issue of documentation standards, or (to make it less dictatorial) style guides. There are plenty of FAQ's, for example, that would have been better if the authors had samples and guidance -- so many times I've seen postings saying "I'm working on a new FAQ; here's a draft, any suggestions?" and finding that a simple template would have saved lots of time and effort.
So to you and your contributors: If you're going to support a metadocumentation effort, try to start by consolidating metadocuments, and (perhaps) providing a linkable source of common dox and linx that folks would probably like to reference.
-- We all have enough strength to endure the misfortunes of other people. La Rochefoucauld
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."
A corporation provides a single, monolithic entity to approach for licencing; an open-source project provides an unkempt mishmash of hundreds of hard-to-find developers with different ideals and personalities; your average company isn't going to bother rectifying licence terms with that many different, unpredictable people.
And what exactly is the problem with that? Let them do their things their outdated ways, who cares? Tell you what: most of the corporations who currently think they're so hot will be bankrupt ten years from now; there is no question that free software will still be around. Their model is wrong, not ours.
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