Re: A new strategy for internals documentation

On 08/07/2013 12:28 PM, Eli Zaretskii wrote:
> internals manual, and the result was always the same: people are
> generally happy with the commentary in the code and don't feel any
> need to go any further.

My personal feeling is that it is harder to edit the internal manual
than to change the .c code.  I feel competent to edit c files to fix a
bug or add a new feature, with some comments in the code and rationale
description in the mail.  However, when it comes to the internal doc, I
don't know how/where to edit because I don't have a global view on both
the internal doc and the source code.  Unfortunately, only few
contributors has such global view.  That may be the reason why some
contributors complain about the internal manual, but fail to post
patches to improve it.

I like the idea that using wiki, which is not very formal, to encourage
contributions on the internal doc, tutorials, howtos, etc.  I had slides 
"Port GDB To A New Processor Architecture: TI C6X" on the GNU Cauldron 
this year, and John Gilmore suggests that "It would be lovely if you 
could improve the Internals manual in the spots where you learned things 
that were not well documented." [1].  It is a very good idea, and I 
checked the internal manual, and tried to improve it.  Finally, I gave 
up, because I can see something is missing here and something is unclear 
there, but I was unable to extract some necessary bits from my slides, 
and add them to the internal doc, it is too hard for me.  Then I'd like 
to convert my slides to several blog posts or wiki pages, which is 
informal, and people also can get benefits from them.

The current Internals is like a book, most of people can't write a book 
or revise a book, but people can write a lot of useful blog or wiki pages.

LLVM is famous for its documentation, go through its web site 
http://llvm.org/docs/, most of them are tutorials and howtos.  Probably 
there is a "LLVM Programmer’s Manual" [2], which is equivalent to GDB 
Internals.  It is quite general, doesn't include much details. 
Contributors and developers can read tutorials and howtos which are 
related to their tasks, and get their works started.

Experienced hackers are too familiar with the code to rely much on the 
internal doc, but newbie contributors need them.  Usually, documentation 
from newbie contributors usually fits the needs of other contributors. 
We need the contributions to the internal doc, and wiki is a good way to 
go, IMO.

-- 
Yao (齐尧)

[1] http://sourceware.org/ml/gdb/2013-07/msg00095.html
[2] http://llvm.org/docs/ProgrammersManual.html