OSDDP: Involving Students With Open Source Docs

cel4145 writes "The Professional Writing Program at Purdue University recently began the Open Source Development and Documentation Project (OSDDP) where students and instructors across multiple sections of business and technical writing are producing documentation for and about open source applications (see the press release or a mirror). The community and project are modeled after the open source development model and based on service learning principles. For example, students are already working on end user documentation and case study analysis for Drupal and market research and analysis for OpenOffice. Completed texts will be published using a Creative Commons license."

Comments

License

[Pan T. Hose]

Does anyone know why the Creative Commons license was used instead if the GNU Free Documentation License? Are those licenses compatible? For example, would it be possible to made that work available on Wikibooks and parts of that documentation incorporated into relevant Wikipedia articles? I hope so, becuase it is going to be a magnificent project and Wikipedia is a central respository of free knowledge today.

Pros and Cons

[fembots]

I can see a couple of advantages such as independant, objective and professional documentation for Open Source.

On the other hand, I'm also concerned that these documentations might not be as in-depth as if they were written by the persons involved in these projects.

I mean, will we see a similar case like "The marketing department never understands what we IT is really doing!"?

Re:Pros and Cons

[bstadil]

not be as in-depth as if they were written by the persons involved in these projects.

I don't understand this. Why wouldn't the people incolved in the project add the In-Depth later sparing them for the grunt work and using their knowledge much better. It seems like a win -win to me

Re:Pros and Cons

[_Sprocket_]

I mean, will we see a similar case like "The marketing department never understands what we IT is really doing!"?

It doesn't matter. If the OSDDP projects don't produce usefully material, it'll sit unused. If it does prove to be usefully, it'll become widely adopted. Just like OSS, OSDDP material will live or die on merit - not corporate politics.

Re:Pros and Cons

[lordcorusa]

On the other hand, I'm also concerned that these documentations might not be as in-depth as if they were written by the persons involved in these projects.

This may be a blessing in disguise. Often times, software developers do a poor job of writing manuals for their own software; they are simply "too close" to the project. Since they know the project too intimately, they assume that intimate knowledge is shared by users. End users should never be forced to learn implementation details of a program in order to use the program, and having documentation written by an outsider may help to make the documentation more task-focused and less detail focused.

An example is the case where a developer makes a program extremely flexible, usually configured manually through a needlessly complex and difficult to understand configuration file. (I won't name names to avoid embarassing anyonr, but this sounds like many open source projects.) The developer thinks nothing of the configuration process, because he understands all of the intimate details, so he writes a huge document describing every little feature and option. Due to the size and interconnectedness of the options, users typically find such documents impossible to understand. In many cases, most users want generally the same few features and are not interested in every option under the sun. (Once again, if you use open source extensively, you will know what I am taling about.) They generally find such focused and useful documentation written by someone without intimate knowledge of the program.

Also, outsiders will be less likely to forgive and shrug off defects in a program. For example, let's say program FOO has a bug whereby any file saved with a name greater than 8 characters causes FOO to fail to save the data. The lead programmer knows the technical reasons for this and the difficult/kludgy steps needed to correct it, so he simply writes in the documentation that users must remember to use names with fewer than 8 characters. On the other hand, a 3rd party documentation writer would not know this, so he would tell users that a bug existed in FOO with respect to file naming, and encourage the users to pressure the developer for a fix.

Finally, a little theory. In my Software Engineering courses, it is stressed as best practice to write documentation before ever writing one line of code. It is also stressed that when code was written first, (as is the case in almost every professional and open source project on which I have worked) a 3rd party should write documentation to avoid just the problems I have desribed.

Re:License-Gatekeepers! Set my information free.

[_Sprocket_]

For all forms of knowledge there are gatekeepers. Even your beloved Internet has a gatekeeper know as an ISP.

My ISP is being a poor gatekeeper then. I can change service to another ISP. I can go to my local internet cafe. I can go the the library. I can wait until I go to work. In all cases, I can access the same information without my ISP either being aware of or having any say in that access.

Yes, lets hold up as a good example of what we'll get, The Internet. OK so you've just read something on the web. So how do you know it is correct?

Something gets printed in a Journal. How do you know it is correct? The same process of peer review and established trust can be done with the web. And, in fact, has been done for quite some time.

Re:Kinda different approach...

[_Sprocket_]

From what I know of the open source world, documentation is one area that people make money on the free product.

A couple points.

First, I some of O'Reilly's tactics quite intersting. For example, they sell a book on Subversion called Version Control with Subversion. The very same work is available online. The book is licensed under Creative Commons. This hasn't been the first work done in this manner by O'Reilly. And that would imply that there is something else to this business than hording documentation.

Secondly, even proprietary software produces a considerable market for technical books. Even for software that comes with complete, professionally writen manuals, etc. (sometimes even some degree of support).

Finally, documentation isn't new to Open Source. There are actually projects with some very good documentation (as rare as that may be). Yet publishing houses have began publishing an increasing number of technical books covering these as well as other Open Source projects.

I doubt better documentation is going to destroy the technical book business model for Open Source software.

Re:Kinda different approach...

[erick99]

O'Reilly's tactics make sense when I think about all of the ebooks and I have perused online and then bought a hard copy because it's more convenient to read and much easier to carry around. Perhaps this has worked for them in the past?

Re:Don't do it.

[Anonymous Coward]

Yeah, right. I've had nothing but good experiences from listing my OSS work on my resume. Employers like it when a youngster has done something more than academic work, and like it or not, OSS is for the most part non-academic software for the real world.

So, imagine an employer faced with two fresh out of school graduates, neither of whom has done any paid work on technical documentation. One went to a school that gives the students toy examples designed by the instructor (and you've all seen what academic examples are like...). The other went to a school that gives the students assignments to work on the documentation of large OSS projects. In the final analysis, the employer would be a fool not to choose the graduate that already has experience on large-scale real-world documentation work, who cares what the license of the software or the documentation was.

and I'll bite back

[TAGmclaren]

You assume I know nothing about the whole controversy, when in fact I do. I've met RMS, I've heard him speak about what drives him.

The quip at the start was meant to be humour. You asked why they're using creative commons - I said because RMS is a hippy-looking MIT drop-out (using the second definition of the word), which is all true.

Now, without wanting to disturb you up there on your soap box, what matters when picking sides over this for most people isn't reality. It's perception. Laurence Lessig is the foremost authority on electronic IP right now, known widely amongst the community for his ideals. RMS is known mostly only within the IT fraternity, and even then people think of him as some smelly monk whose interesting but for the most part to be avoided.

So, assume you're a Joe Blow (no law degree or PhD, as you quite proudly boast) and you have to pick a license. Do you:
a) pick the guy who has stood up in front of the supreme court fighting for the prevention of copyright extensions, and who developed the licence that The Beastie Boys have released work under; or
b) pick the guy that quit MIT, is in serious need of a haircut/shave and who gets up on his soapbox regularly about it should be GNU/Linux, not just Linux?

Doesn't matter about whose right or whose wrong. It's just how it's perceived. I admire RMS, I think the world needs people like him, but I think that what he's proposing is flawed. I think that Linus's philosophy is much more realistic than RMS's semi-communist approach, and in trying to create freedom for the users he denies freedom for the developers - the people whose software it is.

Regardless, the original quip was meant humourously (note the smiley). So just relax a bit, ok? :)

Re:and I'll bite back

[spuzzzzzzz]

I think that Linus's philosophy is much more realistic than RMS's semi-communist approach, and in trying to create freedom for the users he denies freedom for the developers - the people whose software it is.

And yet I have never heard RMS argue that developers should be prevented from writing free software. His arguments revolve around the idea that users should refuse to use non-free software. So it doesn't deny freedom for anyone because no one is prevented from doing anything. It's more of a boycott thing, I guess.

As for the semi-communist comment, free software can promote competition in certain ways. If you have some free software that you need support for, you can shop around for support and let market forces do the work. On the other hand, if you want support from some piece of proprietary software, you can only get support from the original vendor. I prefer to think of the difference between free and non-free software as the difference between capitalism and monopoly, not the difference between communism and capitalism.

Re:and I'll bite back

[cofaboy]

I thought that RMS referred to GNU/Linux that way because he is still hopeful that HURD will become fully operational, this would give 2 systems GNU/Linux and GNU/HURD.

Both parts are required to make an operating system, GNU provides all the support, bells and whistles whilst Linux and HURD provide a kernel.

What is it that people find so damn difficult to understand about that

why not support LDP?

[Anonymous Coward]

This project seems to have larger scope than LDP but it seems it could still live inside LDP. Some of the documentation producted by Linux Documentation Project isn't really that Linux specific.

This is an absolutely fantastic idea

[Catullus]

Universities (in Europe, at least) are mostly funded by the public purse. Why not give students the option of giving something back?

Almost every computer science degree involves some kind of group or individual project. Just imagine the amount of free software that could be produced if all of these projects were released as open source.

Also - forcing the students to handle e-mails saying "your s0ftware is cr@p! where can I get l33t cracks?" is good experience for life :)