documentation

[Matthew C. Weigel]

On Sun, 26 Aug 2001, Greg London wrote:

> 1) software IS documentation.

The stance that puts software under copyright as opposed to patent law
opines that a software is a document, but that's entirely different.

If you write your software in noweb
(http://www.eecs.harvard.edu/~nr/noweb), or otherwise program
literately, it is (probably) documentation.

Entries into ObfC are not documentation, however.

> The only difference between the two is that
> software is a specific sub-section of all possible
> literary works, with the distinction being that
> software is also machine readable as well as
> human readable.

Yes.  And it's that subset that is of interest to the Free SOFTWARE and
Open Source SOFTWARE community.  Not the set of documents specifically
outside that subset.

> 2) Software (open source or not) is of little value
> 	without documentation.

True.  Which is why people like RMS hold the opinion that the
documentation is part of the software, to be held under the same
license, or a similar license.

> If OSI has a commitment to furthering open source
> software, then a documentation license would greatly
> advance open soure. What good is software if you don't
> know how to use it?

You've got the source, why don't you know how to use it?  ;-)

> (as opposed to "the software is the documentation", and
> therefore if you don't understand the software,
> too bad for you)

If open source eschews the political and philosophical issues of free
software, then the biggest reason to use open source software is to
have the source.  Someone who plans on maintaining their code will need
to make it pretty clear anyways.  The software should be the
documentation, but not in a bad way.

> I would like to write a "Teach Yourself Perl" kind of document and
> license it so that it is freely copiable and freely distributable.
> But I don't want people to modify my document and redistribute it
> (i.e. remove any references that it was my document), or roll it into
> a larger document and hide my name, or cut and paste parts of it into
> a hardcopy book and sell it.

How would that be open source, if people can't modify it?  More
specifically, why would the OSI or the FSF care about it, if it's
contrary to their goals?

What if they hack Perl up, and distribute their own version.  Obviously
they want to help people out by giving away documentation as well, but
now their version can't be as well documented as the pristine version
of Perl without a lot of extra effort on their part (or a little
non-obviousness for the reader).

> The reason for pristine-ness is that I was thinking
> that I would put an advertisement on page 3 for a
> book that I am selling. If you read the document and
> think its useful, maybe you'll go take a look at the
> book I'm selling when you're done.

Take a look at the copyright notice used for the rec.martial-arts
Newbie Guide -
ftp://rtfm.mit.edu/pub/usenet-by-hierarchy/rec/martial-arts/rec.martial-arts_Newbie_Guide

Also, take a look at the fate that has befallen it - now that no one
can find Jeff Pipkins, the document has not kept up with the
ever-expanding experience of rec.martial-arts, and hasn't grown to
address frequent concerns of modern newbies.  It is still posted to
rec.martial-arts in hopes of someone finding it useful, but the FAQ has
begun to take its place.

As for an advertisement, simply "Copyright by me, also author of
Barring Foos and Fooed Bars (check it out!).  Derivative works must
not modify this copyright notice."
-- 
 Matthew Weigel
 Research Systems Programmer
 mcweigel at cs.cmu.edu ne weigel at pitt.edu