Re: changes and standards documents
> On Tue, Aug 11, 1998 at 07:34:05PM -0500, Manoj Srivastava wrote:
> >
> > Fantastic. I agree -- as far as these reasons apply to
> > documentation of software. And no further. I have already said,
> > software docuemtnation needs be under tha same licence as the
> > software it self. Why are you belabouring what we have already agreed
> > upon?
>
> You know that it is my opinion that the same reasoning counts for technical
> documents and maybe even for other data entities. If you didn't know it,
> well, then I say it here.
There are technical documents and then there are technical documents.
A piece of legislation is an amazingly technical document (although the
field of technique involved is not our own, and legislation is hard to
see as related to our field), and so is a legal opinion. Should our
"free documentation guidelines" exclude legal opinion simply because
the author does not wish it changed?
More to the point, I think there are several types of technical
documents that have different purposes, different roles, and different
needs when it comes to "freedom". It is counterproductive to say "All
technical documentation must have the same rules as software" without
examining how best the particular technical document could benefit from
freedom.
Here are some classes of technical documents that I would like to
eventually see available under some sort of "Debian Free Document
Guidelines". I'll try not to describe what sort of licenses I'd
applied. Not all my examples are free, or even recommended for
inclusion in Debian, but they are examples of that type of document.
** Software documentation -- documents which tell how to use a
particular piece of software, or how to modify or extend it. Examples
include the GIMP Users Manual, the GCC Internals guide, any source-code
written with "literate programming" tools, etc.
** Standards -- documents which describe standard interfaces, formats,
etc, that programmers are supposed to comply with in order to
facilitate interoperability, consistancy, or some other public goal
outside of the scope of one program or developer. Examples include the
Standards Track RFC's and Internet Drafts, the ISO C and ISO C++
standards, the Open Source Guidelines, the Linux Kernel Coding
Standard, FHS.
** "Technical Opinion" -- documents which state the opinion of a
particular person or group in relation to a technical matter. Unlike
standards, this material is not binding in an of itself, but serves
rather to influence technical decisions or to explain why or how a
particular technical decision was made. Examples include the FYI
series or RFCs, judicial opinions, NTSB crash investigation reports,
etc.
** Instructional material -- documents which are written to teach
technical material. Unlike software documentation, this material need
not be specific to a particular piece of software, or even of software
itself. Examples: The guided-walk-through sections of the Kernel
Hacker's Guide, physics textbooks, US Department of Defence field
manuals on the proper way to brush one's teeth, etc.
The difference between instructional material and software
documentation is, at points, nebulous. Is the "CD-Writing-HOWTO"
documentation for mkisofs and cdrecord, or is it instructional
material. I would probably err towards calling that HOWTO "software
documentation", and reserve instructional material for things which
teach theory or non-specific software-related things.
Software-specific instructional material would probably be better
classified as "software documentation".
==
These categories are not necessarily distinct, as the added comment
about instructional material makes clear. Nor are they necessarily
exhaustive.
However, I feel they have different purposes and goals. As such, they
need to be treated specifically -- or have general principles which
recognise the differences.
Of these four types I feel that software documentation clearly benefits
from dsfg-style freedom. I feel that technical opinion should be as
inviolate as personal and political opinion. I feel that the free
software community would best benefit from standards being allowed to
be inviolate -- a standard with different versions is no standard at
all. I have not fully contemplated instructional material; surely
technically incorrect items should be correctable, but maybe they are
there for a reason (e.g., most physics text books start by giving
incorrect definitions for force, etc, and save the correct,
relativistic, defintions and formula later).
It has already been stated that personal opinion (manifestos, email,
etc) should be exempt from the DFSG for purposes of distribution -- we
recognise the importance of letting people state their beliefs without
modification. I believe that it has been stated that when personal
opinion and technical documentation is mixed in a single document, it
is OK for the personal opinion part to be inviolate, as long as we can
do what we need to with the technical part.
I believe that we are all clear as to why software documentation needs
to be as free as the software it documents. But what about the others?
What would best benefit the free software community, and the documents
themselves?
To take the four points that Marcus brought up:
Marcus.Brinkmann@ruhr-uni-bochum.de said:
> a) Without documentation, you can't use the software.
Of the four classes of technical documents I mentioned, only one deals
with specific software. None of the others make any promises to help
you use "the" software. I don't think this reason applies.
> b) Documentation
> and software are often integrated, for example in context help system.
Again, this is assuming that the documentation is software specific. I
know of no mail program, offhand, that will pull up RFC822 on demand as
part of its online help system. Some software will pull up personal
opinion as part of its help system (Emacs will pull up the GNU
Manifesto, for example), but if those sections are already considered
inviolate, then this is also only an issue for software-specific parts
of the documentation.
> c) Source code documentation (for libraries, for example), are often
> directly written in the source code and automatically generated.
This is explicitly dealing with software specific documentation.
> d)
> Although you choose to ignore it completely --- I think *all points*
> of the dfsg apply to documents for the *same reasons*. The points have
> to be interpreted slightly different. I put my personal interpretation
> in my posting and in the web (known adress).
I see all of your arguments applying to documents that relate to
specific software. As far as I can see, that is already a settled
issue.
> You asked for reasons why for example standards should comply to the same
> guidelines. The reasons are the same, IMHO. I can't understand why you are
> arguing here. You asked, and I gave.
>
> > And I am peeved by the fact that you do not listen. I have
> > agreed to the DFSG for Software documentation too. (I should have
> > stressed that in my last message).
>
> Fine.
>
> > You have not covered anything beyonnd the software+its
> > documentation.
>
> Come on, Manoj. I think I covered quite some things beyond software
> documentation.
I don't think so. Of the points you've raised, I fail to see how they
relate to anything besides software documentation -- besides a
"everything should be DSFG-free" blanket statement.
> I provide the same reasons for standards, too. That you disagree with me is
> a whole different matter, but don't say that I don't provide reasons, only
> because you disagree with them. Mabye "reason" is not the right word here.
> "discussion entries"? "arguments?"
>
> > None of the reasons above apply to non-software-documentation
> > documents.
>
> This is your opinion.
>
> > Stop arguing points we have already agreed on, and lets
> > get a move on trying to decide where we stand on things like FSSTND
> > and the FHS.
>
> Here is my opinion: Standard documents are technical documents and should
> fulfill the same guidlines as software documentation. They should be dfsg
> compliant to be included in the Debian main distribution.
Here is my opinion: Not all technical documents are the same.
Different types of technical documents exist, and they have different
needs with respect to "freedom". The different types of documents
should be evaluated, and dealt with in the way that best benefits the
free software community. Not all types of technical documents will
benefit from being dfsg free.
> This is all I have to say about this, really. But this is only my personal
> opinion. I'll continue collecting all opinions and "reasons" or "arguments"
> in this thread.
>
> Marcus
--
Buddha Buck bmbuck@acsu.buffalo.edu
"Just as the strength of the Internet is chaos, so the strength of our
liberty depends upon the chaos and cacaphony of the unfettered speech
the First Amendment protects." -- A.L.A. v. U.S. Dept. of Justice
Reply to: