documentation

[Matthew C. Weigel]

On Mon, 27 Aug 2001, SamBC wrote:

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

Not as a primary topic of discussion, no.  Unaffiliated documentation
suffers from bitrot at a much higher rate than affiliated documentation
(and how often do you find out-of-date man pages in Linux?).

> Like linuxdocs, there is much documentation like HOWTOs outside of
> software projects.

And, for the most part, they document how the software used to be.

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

Yeah, but the main drive and interest is affiliated software.

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

Then why does open source matter?

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

See my reference about literate programming.  And I do agree - I've
already indicated that I think documentation should be part of the
project.

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

And should you be the one to write the documentation, or a third party?

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

There's a significant difference between being able to distribute
pristine source+patches versus pristine documentation+patches.  One
would normally expect to have to build source.

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

Not in the least aside from the point!  This is why the software and
documentation needs to be licensed together - so that any changes you
can make to the code, you can reflect in documentation.

No-modify licenses simply aren't free or open.

> I agree with the arguments of the previous poster - I will not post them
> again.

I provided two suggestions - but I still don't think his needs will be
served by us.

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

They would be useful, but I don't think that they are vital, nor
relevant here.
-- 
 Matthew Weigel
 Research Systems Programmer
 mcweigel at cs.cmu.edu ne weigel at pitt.edu