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 _______________________________________________ Gnu-arch-users mailing list [email protected] http://lists.gnu.org/mailman/listinfo/gnu-arch-users GNU arch home page: http://savannah.gnu.org/projects/gnu-arch/
