[Gnu-arch-users] documentation and licensing

[Thomas Lord]

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.

Suggestions:

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

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.

-t