documentation

[SamBC]

> -----Original Message-----
> From: Matthew C. Weigel [mailto:weigel+ at pitt.edu]
>
> 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.

Is it not plausible, though, that some documentation is outside a piece of
software and yet still of interest to the Open Source software community?
Like linuxdocs, there is much documentation like HOWTOs outside of software
projects.

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

But some documentation is outside software, which FSF seem to recognise in
their (not very good IMHO) FDL.

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

I would assume this is a joke, but I'll refute it anyway.

1) Source can be quite difficult to interpret

2) Not everyone is that capable.

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

No, no no! Software *always* needs documentation. I am currently employed as
a programmer, and my code will be left when I finish this job for others to
maintain. So it needs to be clear. I need documentation on two levels as
well as this to make it clear as glass - for developers, and for users.
Documentation other than the source will *always* be needed.

Besides, some of the issues open source holds dear are the same as those of
free software, but for practical reasons, not philosophical or political
ones.

> > 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?

Well, the QPL was approved by OSI wasn't it?

> 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).

True, but aside from the point.


I agree with the arguments of the previous poster - I will not post them
again. I suggest documentation licenses (for standalone documentation
outside of a piece of software) are vital, with a similar level of variety
to the range of software licenses. They should be separate to deal with
these specific issues.

A BSD-style one is not necessary, as the BSD license will do (I believe).
However, ones similar to each of GPL, LGPL, and QPL would be a good start.

My two penn'orth


Sam Barnett-Cormack