[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gnu-arch-users] documentation and licensing
[Gnu-arch-users] documentation and licensing
Wed, 18 Jan 2006 09:56:30 -0800
I have a suggestion for people interested in fixing up the
documentation and also a warning.
I'll mostly skip the "GFDL: yes or no?" question. Historically,
licenses like GFDL were actually quite important. Times are
changing and I'm not sure there's any good reason any more to
use such a license for Arch documentation. We could spend
hours and hours debating that only to arrive a conclusion that
we already have consensus about.
1) Yes, use the GPL.
Arch reference and tutorial documentation is, as much as
anything, commentary on the code. There should be
no licensing obstacle to copying parts of the manual
to the code or to deriving parts of the manual from the
2) No, do not use TeXinfo or Docbook -- go for ASCII-art, Wiki-style
A lot of very important uses cases for this documentation
involve dealing directly with the source. Other important
use cases involve viewing the documentation on what is essentially
a terminal. Whether you want to use Awiki or roll your own,
I suggest using a mark-up syntax in which people directly edit
a nicely formatted plain-text version of the text -- which is
unambiguous enough to be parsed to recover a tree for subsequent
processing by TeXinfo, Docbook, or similar. Awiki itself (which,
yes, is incomplete) is aimed at letting people define pretty
plain-text syntaxes for particular XML Schema. One of the
goals of Awiki is that `cat(1)' is a useful formatter for translating
documentation for a plain-text display.
3) Somebody make a plan.
It should be easy to divide the project of making a new manual
into lots of *mostly* small pieces. For example, reference
documentation has one entry per command -- if several people each
pick off just a few commands the whole job can be done quickly.
I suggest that "a plan" would include: (1) an outline of the intended
manual, with consensus achieved over that outline; (2) a markup
language choice (again, w/consensus -- this is prbly the hardest
part of the plan to get agreement on); (3) "house style" notes --
an evolving document containing good advice such as "write in
complete sentences"; (4) one or a few editors who are at least
pretty good at copy editing. The outline in such a plan is the
task list -- volunteers can pick off outline items and when all of
them have been picked off, the first draft documentation is ready.
4) If there is demand for a printed form....
Consider Lulu press. I don't mean to be too much of a shill --
especially for a company I have no personal interest in -- but
that company strikes me as a nifty and useful hack. It is an
easy and cheap way to get something like Arch documentation into
print. I wouldn't expect printed documentation to generate huge
profits. A simple and agreeable thing to do might be to arrange
that any profits go to the FSF or its sister organizations -- any
money generated that way could be noted as a gift from the volunteers
who create the documentation. (Of course, if it really takes off,
perhaps the FSF will itself take to publishing a version.)
Ok, so, the warning:
Arch is in a tough, awkward spot. I don't think anyone would argue
that it should remain frozen with the current implementation or UI.
We do know how to do lots of parts of Arch better, now. We know
empirically that many users will prefer a system with worse
functionality but a more familiar, perhaps simpler UI.
But for obstacles money and yadda yadda yadda here is where I had
once *hoped* to be now:
a) 1.x maintained by "somebody else" with conservative, professional
tastes. (And, cool, that seems to have come to pass.)
b) A few people (not just me) integrating all the lessons we've learned
from Arch, git, Subversion, Darcs, monotone, etc. to make arch 2.0.
We have all the pieces and know-how on the table. The Arch
community, more than the communities of those other projects, has
"the big picture". The Arch community, more than the communities
of those other projects, has a handle on how to make something
*simple* yet widely applicable and portable (yes, we learned
portability lessons "the hard way"). It's really the next logical
step to sum up all these lessons as Arch 2.0. Of course, while
(a) has come to pass, (b) is not on any map.
Suppose (b) were on the map. That would impact the documentation
project in a big way. Arch 1.x would have a distinctly finite
lifetime. The main push would be to get 2.0 on-line. It's not
at all clear that documentation written for 1.x would be all that
useful for 2.0.
So a documentation project is a good idea, sorta, but also a problematic
idea and one that comes from a defeatist set of assumptions. The Right
Thing here is a push for 2.0 in which case improving 1.x documentation
is cool but there's no reason to make too big a production of it --
that would be provisional documentation.
That push to 2.0 doesn't seem to be coming, so, is there a Right-enough
Thing? Does it make sense to invest a lot of effort in 1.x docs?
Absent 2.0 I think it likely that Arch will die. Some ideas will
live on in other projects and other ideas will be reinvented in
other projects. It's hard for me to guess how quickly or slowly
that takes place so it's hard for me to form an opinion about how
worth it it is to work on 1.x docs.
- [Gnu-arch-users] documentation and licensing,
Thomas Lord <=