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
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.
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[...]
Find free books.
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."
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...
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.
Personally I think Free software has much better documentation. Yes, I am counting e.g. O'Reilly titles as Free Software documentation. I glance over to my bookshelf and see such useful titles as "sed & awk", "GNU Autoconf, Automake, and Libtools", "LaTeX", "Linux Core Kernel", etc etc.
Ryan T. Sammartino
"Ancora imparo"
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
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
Above all, it has proven that you can burn through investor money in record time. Besides, who cares about money? The very existence of free software proves that quality can be produced without monetary incentives.
Free software will still be around, yes, but it will no longer be able to improve at the exponential rate it has been without corporate backing and most importantly money going into it.
Corporate backing hasn't helped free software one bit. Compare the contributions of Redhat or IBM to the contributions of the KDE project. Redhat stinks of money and still can't produce anything of significance. The real stuff is happening elsewhere. It's the enthusiasm of the hackers. Redhat goes bust today, Alan Cox will find some other job, the whole story is forgotten the day after tomorrow and everything goes on exactly as before. And if Alan loses interest, there are ten bright young hackers eager to take his place.
Free software has grown long before the suits found it, and will continue to grow long after the suits have forgotten it. You don't need money to induce people to do what they want to do anyway.
Hrm. Package maintainer mucks around; software gets stigma of being Non-Free. Anyone else a little concerned about that?
Stating on Slashdot that I like cheese since 1997.
...there are people that make a living of documenting the mes^H^H^Hprograms other people leave behind.
Sure, and more often than not the result is inferior compared to what the developer could have done in the time it took out of his or her time to explain to the technical write what the technical writer should write. A much better scenario (ideal really) is for the developer to write some raw, perhaps crude, but complete documentation minus API references, tables, illustrations, and similar. That will greatly accelerate the technical writers job of organizing and presenting the information more formally.
And remember we're talking about Free documentation here. A technical writer who was good enough to interpret someone elses code would probably write code themselves instead because they have a choice.
(Not the person who reported the problem or made the decision to put the docs in non-free, but the guy who gets to go through and fix it.)
The solution presented was
Open Content - which seems to have some use in the academic fields.
Of course, when I check my link, the site is down, which probably means it's been checked and slashdotted already.
However, I do see some limitations with the opencontent project, and seeing a generalized GNU license for written works would be nice.
Wikipedia seems to favor volume over accuracy. The pages I looked at all tended to display the writer's agendas fairly plainly. Some are very misleading, either by omission, or by stating opinions as facts.
Writing factual articles is difficult. It requires research and responsibility on the part of the writer, and dedicated, professional peer review from above to weed out the writer's personal agendas, or point out missing information that was overlooked. That's what you get when you look at a dictionary, or a professional encyclopedia, and I just don't see it there in Wikipedia.
It's not enough to have lots of people's opinions on a subject, or only some of the facts, or a collection of truths and untruths. If a source of information isn't dependable, it's useless to me.
Jon Acheson
All opinions expressed herein are my own, and not those of my employers, who are appalled.
Being a technical writer is a separate skill from being a programmer. Seriously. Some really good programmers are decent technical writers, a very few are good. Many are terrible.
It is usually the case that for a small utility, less than a few pages of documentation will allow people to use it well. The man pages are examples of this. But they are also an example of the limitations of this approach. Sometimes I come to the end of a man page, and find myself asking "What does this do? And why would I ever want to do it?" (This usually happens when I'm looking up something I've run across in a shell script that I'm trying to figure out.) So the man page would tell me how to format the command to run without error. But didn't help me understand the script.
Now, I admit that it is rare for a man page to be quite that bad, but few of them are pleasant to read. You need to know ahead of time what you are looking for. And even then they can be a bit cryptic.
Well, man pages aren't intended to be full documentation, but did you ever read the old CP/M manuals? Compare those with the old IBM manuals and you get an idea of just how important a good technical writer is. The IBM manuals were intended to be references, but they were actually good enough to learn from (if you were patient). The CP/M manuals were difficult to read even if you knew exactly what you were looking for. But they were BOTH good examples of careful, accurate, technical documentation. And technically there wasn't much to choose from between them.
.
I think we've pushed this "anyone can grow up to be president" thing too far.
Yes, poorly-documented, half-finished, unorganised quality.
Show me one compiler that's better documented than gcc, and then we talk. Show me one web server that is more complete than apache, and then we talk.
Why else do KDE and GNOME look more or less like wholesale ripoffs of CDE, Windows, and MacOS?
Because if your target is end users, you need to avoid all surprises. That's why CDE, Windows and MacOS look like ripoffs of each other in the first place. There are plenty of innovative interfaces in the free software world, much more than corporations ever invented with all their R&D money.
Why are there no free *games* written on top of the Crystal Space engine?
Why are there no free books, no free music, no free movies? Don't ask me, ask your friends the corporations. Are hackers supposed to solve all problems in the world?
And your claim that operating systems don't need design, but graphical interfaces do, is ridiculous. What do you think how much R&D money Microsoft burned on the Windows NT kernel? Linux did the same, five years earlier, with no budget.