Re: A new strategy for internals documentation

Yao Qi
2013-08-08T03:45:53Z

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