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.

Quality documentation

[spencerogden (49254)]

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.

Leave the politics out of it.

[Starship Trooper (523907)]

All this bickering over licence is ludicrously counterproductive. Licences don't sue people, people do. I hardly think the writer of a GPL piece of software would care what you do with the accompanying documentation, and it is baffling to me why the Debian nuts think documentation needs to be under its own special licence instead of using the GPL along with the software it documents. The reason I switched to open-source software was to get away from all the stupid EULA politics and policing of the traditional software world. I hate to see this pigheadedness seep into the open-source world.

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?

Re:Leave the politics out of it.

[ryants (310088)]

Note he writes that he couldn't sign a license agreement... hrm; like the license agreement he forces anyone who wants to put any GNU code into their projects to do ?

From the GPL, section 5:

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

You aren't forced at all. If you want to benefit from his (and others') work, then these are the rules you have to play by. You can't take without giving. If you don't like it, don't use their work. It's that simple.

That's what made open source software so nice; you could hack without worrying about strange, arbitrary laws governing which code you can use and which you can't. Just download the code you need and go; everyone is happy.

That what the page at http://www.gnu.org/licenses/license-list.html#GPLC ompatibleLicenses is for. Makes it simple.

it's becoming just as bad as (or even worse than) closed source software.

How do you figure that? You have 0 rights with closed source/non-free software.

Re:There's a difference

[AxelBoldt (1490)]

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.

Why so complicated?

[chuck (477)]

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.

Fantastic...

[pongo000 (97357)]

Now we have three open-source/free software doc projects: The featured project, LDP, and OSWG. So much wasted effort by so many people who could do God only knows what if they were to combine their talents, rather than taking their ball and running home at ever little perceived slight.

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.

Re:Fantastic...

[Guylhem (161858)]

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.

Re:Fantastic...

[wfrp01 (82831)]

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 [gnu.org]:

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.

technical writers need money too

[perdida (251676)]

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.

An excellent reference

[Leeji (521631)]

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. [ucr.edu] Or, they run out to buy expensive Linux device driver manuals when the best resource is available online. [xml.com]

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 [wearcam.org] approach would spread -- and students wouldn't need to spend $500 per semester on textbooks. And unfortunately, the Project Gutenberg [promo.net] 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 [upenn.edu] has a lot of good information.

The "problems" went the other way around

[coyote-san (38515)]

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.

Re:The "problems" went the other way around

[wfrp01 (82831)]

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?

Re:The "problems" went the other way around

[Error27 (100234)]

How exactly is Debian making a big deal about this?

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 [slashdot.org]
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 [linuxdoc.org]. I really doubt your document is on it.

Example of free documentation?

[joestar (225875)]

Mandrake Linux manuals:
http://www.mandrake.com/en/doc/81/en/ref.html/fore word.html#LEGAL [mandrake.com]

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

Sounds good; promote standards

[Spinality (214521)]

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 should appreciate Debian

[argoff (142580)]

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.

Wikipedia

[javilon (99157)]

Maybe what is needed is a wikipedia [wikipedia.com] 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.

Coders Must Document Their Own Work

[KidSock (150684)]

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.

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 ;-P

Re:Coders Must Document Their Own Work

[SCHecklerX (229973)]

The problem with this is it takes MUCH LONGER to write the documentation than it does to write the original software!!

I have a lot of little utilities, probably very useful to the public, that I've written for myself here, but to release them to the public would take a lot of time in code cleanup and documentation that I simply do not have.

I've tried to release some of the better stuff, but documenting and making things not crash and be secure is a very time-consuming and boring task.