documentation

[sambc at nights.force9.co.uk]

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

accepted as true, but not necessarily universal or true (LFS being a good example)

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

For the most part, perhaps.

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

but there can be such a thing as good, well-maintained documentation which remains valid despite being outside a sfotware package, through two methods:

1) the author or others continue to maintain it.

2) it's about something so universal it doesn't change for years and years.

>> 1) Source can be quite difficult to interpret
>>
>> 2) Not everyone is that capable.
>
>Then why does open source matter?

I hope this is still a joke. Opensource matters for lots and lots of reasons, and being able to look at the source isn't the key one. Being able to modify it in some way is important, as are the none-source-specific parts of the OSD, such as redistribution.

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

I should do essential documentation, and if anyone else feels the urge to do an in-depth analysis of techniques, or write a d.a.d.s. tutorial, that's all to the good.

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

And in some cases documentation may be distributed as, say, SGML, to be built into a more readable form by the user.

Further, a good way to implement patch-style updates for docs is used on my sLODL, and in the GNU FDL to a certain extent (last I checked).

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

absolutely. so the external docs someone writes should say "written to work with version x.y.z.blahblah - functionality with other versions may vary".

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

but modify with patches is.

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

and you are in a position to make that judgement?

>They would be useful, but I don't think that they are vital, nor
>relevant here.

this is a list to discuss licensing, why not? I think they woule serve a more clear and present need & purpose than a glut of software licenses...


SamBC