Re: [Gnu-arch-users] documentation and licensing

[Andrew Suffield]

On Wed, Jan 18, 2006 at 09:56:30AM -0800, Thomas Lord wrote:
> 2) No, do not use TeXinfo or Docbook -- go for ASCII-art, Wiki-style

Docbook is primarily useful for when you're targetting *print*, but
want a better online version than a pdf, or the somewhat miserly
results latex2html generates.

texinfo is good for annoying everybody. I think that's about it. It's
almost universally reviled. Users hate it, non-GNU developers hate it,
vendors hate it.

Ignoring for now the possibility of creating yet another documentation
system (on the basis that everybody does that and they all suck so the
next one is likely to suck too), I see three practical options right
now:

 - Basic HTML. Little more than minimally-annotated text, optimised
 for web access, pretty nasty for everything else but at least you can
 throw it through html2text.

 - Plain text. Difficult to convert to HTML or print, but if you don't
 care, this is by far the easiest option.

 - latex. If print matters to you at all, this is *the* way to go, and
 just put up with latex2html for the web version. Plain text output
 is easy.

Yeah, they all suck in some respect.

Maybe in six or twelve months there could be a new markup system that
does better than one or all of these, but right now there isn't, and
on the whole it seems unlikely to happen.

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

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

This is essentially what I said a few months back. I also included a
rough explanation for it: it will be a long time before the fallout
from the corporate RCS wars has faded sufficiently to support real
development. Right now, it's not even driven by 'simpler UI', but by
the *belief* that a UI is simpler. In essence that is nothing more
than marketing.

In a few years, if all the crap settles down and people have had
enough time to learn to hate all the current systems for their
fundamental limitations, then something new which removed those
limitations could become viable. Right now, I doubt it.

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

I have been contemplating technical solutions for surviving in a world
filled with numerous crappy incompatible RCSes, but right now I don't
think I can be bothered to implement any of it, since I don't really
need it myself.

-- 
Andrew Suffield

signature.asc
Description: Digital signature