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
Great, the mess in /dev will be libre documented, but it will still be a mess.
Not to be confused with the 'GNU Bowel Movement'
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
Free as in beer or free as in speech?
You die too easily.
GWM = GNU Writing Movement = Gay White Male. Could they be any more obvious about it?
Free/open software desperately needs much, much better documentation in two areas: End user docs and architecture/design/implementation docs for other programmers who want to work on or with the code. Until the basic economics of f/o software change, those needs won't change, either.
Link in the article is broken, this is the fixed one (hmm, what's this it says down here, could it be "Use the Preview Button! Check those URLs!")...
NZ Electronics Enthusiasts: Check out my Trade Me Listings
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.
Incorporate some bonified Free Software that can syncronize with this database of the internet and you have just another program with a purpose. A good puprose! Have a plan for developers of every software package in existance to submit their helping text to this database. This way, you don't have to visit a program's author and download a compressed archive, extract files, read the INSTALL and README instructions, and run the three or four de-facto commands to build and install.
That was my bone with Linux, see... To get a program, I search freshmeat.net, search Linuxgames.com, and happypengiun.org for something of use and I find something that is a pain to install. Why not make a database that project authors can submit their documentation, provide some easy-to-use URL's, and a GUI for installing the program or at the verry least an intelligent Makefile that uses some calls to gtk-shell, TCL-TK, Perl, or Python; or anything you can think of that won't segfault or crash in its own installation scripts. We need that, and better for all authors to have the help menu on their program to point to this helper database.
Now, now... You trolls are all going to tell me that is the purpose of freshmeat.net and sourceforge.net. Well, those two websites are environments suited for web-browsers and they are both tailored mainly to developers and enthusiasts. Slashdot is such a place where we cann all discuss software, events, and all kinds of stuff. In fact, many Linux programs are first planned from a good idea from a slashdot reader; we are a good development forum I might add. Back to the software I'm talking about, let's think of our grandparents and cousins that don't understand what "compile" and "symbolic link" means. They should be using a help database system that lets them search for a peice of software based on search criteria and the database says simply what a peice of software does and provides a 1-click button for testing your system for compatibility, compilation, installation, setup, and more supporting text on howto use a software package; like flipping through the pages of an encylopedia, not like using xpdf, man, emacs, vi, and all the popular legacy software I forgot to mention.
Microsoft has a help database in their operating system. It isn't used much, but we should improve on that idea with it being built upon a gui, searchable, etc.
without prejudice
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
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.
Free documentation = freedom to share it, people will still get paid to write it.
If you use Linux, please help development of Autopac
I'm so sick of nitpicking about "kinds" of free; ENOUGH already.
/usr/doc/LDP etc is skipped or removed, because its all outdated garbage. Shit, some of it's more than three years+ old. Its getting to be a challenge to find docs that are actually current with the status quo of linux software.
Why is it that all these "free license" people always seem to "greedy"? It's not enough for me to write something and hand it to you with my blessings, I have to GIVE you ALL rights to what I've written?
All this comes off as petty bickering. Everyone involved needs to stop inventing cute little acronym "groups", and start writing documentation; most of it sucks anyway; whenever I install linux these days, all of
Why don't you boys stop the pissing match over whose license is "right", and actually fix the fucking 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.
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.
Another documentation project! So what? It is like all those new programming languages that crop up because the old one is "not good enough anymore", and the new one is supposed to replace it! This usually meant that people have an extra language to learn. Look at C++ and C, C# and JAVA, and I'm sure there are more. Creating something new does not make the old one (which works just fine, thank you) obsolete. I agree with a href="http://slashdot.org/comments.pl?sid=24969&ci d=2712435">previous comment that all this bickering is counter productive. The best way to fix a problem is to "work" on it not start something new.
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
Wikipedia.
http://www.wikipedia.com if you're frightened of links.
I moderate at +3, Highest Scores, and I always mod down.
If you don't like it, vote me off the island.
See subject
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.
Honestly, I think copyright needs to be done away with. It is an unnatural restriction imposed on something that is inherently not scarce once a single instance is produced. Yes, "information wants to be free" is old and sounds hopelessly naive to many, but it describes the nature of information much better than any concept of scarcity. There has got to be a better way to motivate people to create information than offering them control over it. Maybe there would be less noise that poses as information and more people would be willing to contribute. Freed from the hassle of dealing with legal aspects everyone could concentrate on the content without fearing that someone rips them off by selling "their" information.
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."
Public Domain is FREE. The GPL is a restrictive legal license.
Really now, I've read some of the arguments here about freeing documentation, and im wondering who really will make the effort to create the docs for this project. I'm of the persuasion of making minimal docs and then allowing other companies to sell it as a service (or even as a "For Dummies" book). This way Linux could be viable and all the "windows heretics" could see the light of a free OS.
I mean making everything free would just make people homeless. And it would take up a lot of man hours. I think people should get the basics, or then look us newsgroups or whatever, or get a proper manual for the info. An example is the recent debate of QT vs Gtk on slashdot (can't find the link for some reason). People complain Gtk is really badly documented compared to QT. Well all that is needed is minimum documentation to work - companies should be encouraged to develop full documentation (and maybe tidy the source up). The work can be copyrighted and sold for all I care (can't think of disadvantages), with people getting jobs due to open-source. This should encourage others to take it more seriously.
having done some technical writing myself, i now know the difference between software developers and technical writers. software developers make the software (DUH), but also know MORE than anyone else about what the project / software is about. however they usually know jack shit or close to nothing about writing and eloquent expression. because of this, they hire technical writers. the problem is the fact that technical writers write better (DUH, again), but also usually dont know THAT much about what they are writing, and the developers end up unsatisfied with the result.
writers should work in conjunction with software developers to document their work. yuo cant have a bunch of guys contribute to the cause...
finally, developers usually find the docs the MOST ANNOYING part of the process of completing their project / producing their software. therefore...we can't really reach a golden mean...and creating an organization of sorts to document things is NOT incredibly useful, IMHO.
however, the rating system might remedy this. the developers might not be pleased and be too lazy to write their own docs, but can write the written stuff.
eh, whatever: hate to judge prematurely...so good luck guys!
QED
BSD is for people who love UNIX. Linux is for those who hate Microsoft.
There is also the trouble of actually finding the authors who hold the copyright to the code; there is a TON of old, unmaintained software that has outdated e-mail addresses and no other way of contacting the author. And for large collaborative projects like Linux, copyright is split between the thousands of contributors that have added to the project over its lifespan. 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.
Loneliness is a power that we possess to give or take away forever
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...
The point I was trying to make is that this sort of thing shouldn't be a fucking problem in the first place. Debian has obviously survived for the past five years without nagging the LDP to make silly little fixes to their licences; it's positively atrocious of them to go "Change your licence or we're dumping your documentation; you have 48 hours to decide". A problem as pointless and minuscule as this should not be a big enough deal to make the Slashdot frontpage twice, nor should it require what amounts to an ultimatum to solve.
Also, licences don't sue people. I said this in my parent post, but it must be reiterated. An open-source licence is not so much a diction of what can and can't be done with the code as it is a statement of the author's intentions. I seriously doubt the Linux Documentation Project is going to call the Debian Linux distribution on some technicality of the GPL or DFSG. What could have been solved peacefully in a relatively quiet way by friendly parties shouldn't explode into an ultimatum situation and the discarding of reams of perfectly good manuals and HOWTOs only to be rewritten half-assed.
Loneliness is a power that we possess to give or take away forever
While I can appreciate your idealism, the "outdated" corporate model has proven to make money now. Of all the open-source companies, only Redhat and Apple are making a profit; Redhat by essentially having a monopoly on enterprise-level service and support for Linux, and Apple by receiving the majority of their profits from hardware. 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. The Gordian knot of licencing in the free software world only serves to stroke the egos of RMS and the other zealots, while chasing away the money and support that could help bring their vision of "world domination" to life. People have been predicting the death of Microsoft and closed-source software since the inception of the GNU project, and yet their business model still is firmly entrenched because it works.
Loneliness is a power that we possess to give or take away forever
why do you idiots have to make everything so complicated? i'll stick to the MUCH simpler Microsoft Windows.
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
All right, I'm sure your motivations are pure and all, but the fact that you're doing this under the GNU name is simply bound to get Stallman and his anal-retentive ways tangled into this mess. I have nothing against the GPL or the BSD licence (though I find BSD to be a tad too free, if you know what I mean), but GNU projects have a history of GPL bigotry and "our way or the highway" elitism which has caused no end of grief for many open-source projects (KDE, anyone?) and turned away many parties interested in Linux. From the poorly-written Slashdot article, I got the impression you were in the business of replacing non-compliant documentation, not merely cataloguing it as you say you are doing.
Loneliness is a power that we possess to give or take away forever
...seems to be more a bunch of armchair lawyers than technologists or software engineers. Jesus about 90% of the stories on Slashdot are lame "Wah! Blah blah broke the GPL!" or other such tripe. Code and get over it for crying out loud you bunch of sissies.
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
Do developers really want help in this area? Would they appreciate documentation developed for their code (I mean end user documentation, not architectual or maintenance documentation). If so, why don't I normally see such a request in the code I use or on the banner of the application? I'm just wondering if people think developers would appreciate this or be put out by a suggestion or submittal.
Furthermore, after reviewing this GPL our lawyers advised us that any products compiled with GPL'ed tools - such as gcc - would also have to its source code released. This was simply unacceptable. As the concept of the FSF and GPLed software is, "If you let someone light their candle from from yours, do you then have the right to tell them what to do with that light?" this comment, however politely stated, is practically speaking to another point entirely. Apparently the actual services the company provides aren't intrinsically worth the monies being spent by their clientele, that is unless they are in the business of writing and selling APIs and the like. "To the victor, goes the spoils" avails to discussion based in strategy, not armaments.
...and finaly I know what I want for christmas.
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.
Faq-O-Matic is an attempt to deal with some of these problems. Look at the idea... not the ugly colors in the frames. btw 63.96.88.170/halt/ is my attempt at an open source document.
Please use [ informative / summarizing ] SUBJECT LINES
Flame me here
No? Bad. IN the "Real World[tm]" there are people that make a living of documenting the mes^H^H^Hprograms other people leave behind.
IANAL but write like a drunk one.
I feel that certain people don't like the LDP because its the LDP and not the GNU/LDP. So they want to reinvent the whole thing and "de" credit those that worked on the LDP.
Inner politics will hurt these projects more than anything Microsoft could do. Politics erode the sense of giving and being part of something larger. Which is an aspect of why people give freely of their time.
*Some* programmers are poor writers. Others may enjoy writing. However, good programmers often get paid twice what a competent technical author gets; hence it is more efficient use of company resources to get the technical author to do time-consuming editing.
I think writing manuals should be a collaborative project between the programmers, the author and possibly a graphics designer, with each contributing to the documentation as they are suited.
(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.
The term `free' causes so much confusion these days... How about replacing it with `unrestricted' (for free-as-in-speech) and `gratis' or `no-cost' (for free-as-in-beer)?
Ceterum censeo subscriptionem esse delendam.
... and start writing some docs. This is one of the main OSS problems, go to sourceforge and see how many projects are there, we are always reinventing the weel (look at kde/gnome), and instead of creating a good product we focus on "showing what i can do".
\
This is the same thing as with documentation, why do we need another documentation project?? if anybody wants to contribute there are plenty of things to do, i dont think the priority is "another great project" to provide access to the docs that havent even
been finished.
Life isn't like a box of chocolates. It's more like a jar of jalapenos. What you do today, might burn your ass tomorrow.
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.
How many times have you done
man somecommand
only to be scolded that this man page is begrudgingly provided to you as a "courtesy," and that to get the full documentation, you have to learn someone's nonstandard, failed attempt at hypertext documentation.
Like it or not, 'man' is the standard for Unix documentation.
Like it or not, HTML is the standard for linked documents.
Hey, Windows users, there is no such thing as "forward" slash, there is only slash and backslash.
This was a very interesting and thoughtfull post about document templates, but my browser ate it. Feel free to imagine something nice here.
pinkNoise
In the limit, information workers become wards of the state, supported by the National Endowment for the Arts, (IS Division), where they will compete with various performance artists and virus writers who have successfully submitted grant requests to get NEA(ISD) handouts. They ride on the goodwill of real workers who create goods and services that cannot easily be duplicated or automated - which in the world of robotics means the people who braid hair and the ones who change diapers (the so called "heads or tails faction"). Farmers, miners, assembly line workers and other traditional value creaters (as opposed to VARs like grocers etc.) eventually disappear as well, as their businesses succumb to the ability of the average person to gain access to their goods under the guise of "freedom". The Freedom of Access Act of 2034 evicerates their ability to protect their produce against people who successfully point out in courts that the locks on these facilities are easily hacked, and therefore should not be allowed to keep out the people who need or want access.