Re: Merging manuals (was Re: How do you use GDB to debug GDB)

[jtc@redback.com (J.T. Conklin)]

>>>>> "Stan" == Stan Shebs <shebs@apple.com> writes:
>> As a complete asside, it has also been suggested that the two documents
>> be merged.  From memory GCC did this.

Stan> GCC still works this way.  GDB has it as a separate document
Stan> because that's how John Gilmore set it up, and although I wasn't
Stan> there, I bet Roland Pesch, as the only professional tech writer
Stan> at Cygnus at the time, strongly objected to gluing the internals
Stan> documentation into the user manual.  (Probably the same way
Stan> would have happened to GCC if he'd had any input into GCC docs.)

Stan> I've thought about merging them from time to time.  The main
Stan> argument against merging should be obvious; the user manual is
Stan> just that, and should not include anything that might mislead or
Stan> intimidate users.

I think the split users/internals manuals is a good thing.  I've seen
the puzzled expressions of folks when encountering the gcc manual for
the first time.  They were quite relieved when they learned that they
didn't have to learn about all that stuff just to use the compiler.

A further split into a users and a reference manual is also desirable.
I can't recall a single manual where both introductory and reference
information was presented well.  Separating them into two allows each
to focus more clearly on it's target audiance, but the pair would
probably be more difficult to maintain than one.  Because of that, I
can't recommend we go that route.  

But it is something to consider as we continue editing the manual, I
think our current scheme leaves a lot to be desired.

        --jtc

-- 
J.T. Conklin
RedBack Networks