[Gnu-arch-users] Re: doc formats

[Thomas Lord]

Matthew:

> Anyway I think you're trying to solve a problem that 
> doesn't need solving for the purposes of arch docs.
> Not it in the medium term anyway.  We can fix it later
> if needed with some eyeballing and programming.

> YAGNI, simplicity is its own reward etc ...

What do you think of this idea?:

* Evaluate the Labor Pool

  A lot of people agree that documentation work is desirable.
  A show of hands: are there any who think that important 
  enough that they want to volunteer a few hours to the GNU
  project to work on it?

* If There's a Point to It: Someone Self-nominate to Draft an Outline

  If there's a labor pool for documentation, someone make an
  outline that can be divided up into small tasks done more or
  less in parallel.

* Just Get the Content Out There, Legibly

  Do it in plain-text using the Emacs outline-mode style
  of section and subsection headings, like this message.

** For Example...

  I just wanted to add a subsection for no other reason
  than to show what two asterisks look like :-)

There won't be all that many pages at the end, I think.  If later
everyone is slapping their foreheads in the sudden realization that,
after all, `nroff(1)' is the One True Way -- it'll be easy to 
patch up.

As for this long digression about doc formats: making practical
trade-offs is a Good Thing -- if you understand what trade-offs
you're making.

-t

      A novice was trying to fix a broken lisp machine by turning the
    power off and on.  Knight, seeing what the student was doing spoke sternly,
    "You cannot fix a machine by just power-cycling it with no understanding
    of what is going wrong."  Knight turned the machine off and on.  The
    machine worked.
                                        -- LAMBDA.TXT