[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gnu-arch-users] Re: doc formats
From: |
Thomas Lord |
Subject: |
[Gnu-arch-users] Re: doc formats |
Date: |
Sun, 22 Jan 2006 11:07:46 -0800 |
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