Re: [gnugo-devel] doc patch and structure discussion

[Arend Bayer]

On Fri, 22 Mar 2002, Gunnar Farneback wrote:

> * How useful is it overall?
> * Which parts are good and which are bad?
> * Is anything so bad/useless that it would be better to omit it?
> * What improvements would be most important?

To me, it was definitely extremely useful. I had the dvi-file opened on
my desktop for 2-3 months, and looked at it regularly. Also, I am not
sure whether I would have started looking at the GNU Go code at all if
there had not been the documentation.

I agree with most what has been said, in particular that the overview
chapter needs a revision. It took me quite a long time until I had a clear
concept about the order of events in genmove. Yes, it is explained in the
overview chapter, but I never bothered to read a chapter that starts by
defining what a worm is. The explanation of the board array should get moved
to the board chapter I guess.

Some general considerations depend of course on which readers we are aiming
at. I second Trevor's point that it should be very invitational to possible
tuners. Programmers that want to use the API won't be scared off if they
have to search a bit for the relevant information, they will most likely
have a look at the code anyway. 

So I suggest to add a chapter on tuning right after the "Analyzing" chapter,
with references to more detailed explanations. For the engine, I'd
personally prefer a top-down structure. That is at least the order in which
I tried to understand GNU Go.

Then the remaining stuff (API, sgf-handling, GTP) should come at the end.

> 3. Of the 200 and a few pages, about 33 are spent listing functions.
> Sometimes I get a feeling that this is just a waste of paper. In
> particular, the list in section 9.7, "Move Generation Functions", is
> four pages of mostly various add_xxx_move() and set_xxx_value()
> functions. I just can't see a good reason for this list.

I never used these functions lists. As every function in the code has (or
should have!) a preceding comment explaining what it does, I didn't see
a point in consulting a more likely outdated documentation. So I'd suggest
to remove these lists or reduce them to important complex functions, where
more substantial explanations could be given than in the comments.

(Such a list should definitely be substantially different to the output of e.g
`grep -C "^.\*" move_reasons.c` to have any reason to exist and be maintained.)

I can help with all this, but of course I will address the code/tuning
matters that I want to do first.

Arend