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

[Daniel Bump]

> 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. 

The four web pages at http://www.gnu.org/software/gnugo/tuning.html
are supposed to be invitational to tuners. Two on pattern tuning,
two on owl tuning.

Are these pages successful?

Of course they are somewhat out of date. Something like this 
could be put in the Texinfo doc.

> 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.

They shouldn't be out of date. I updated most of them in the last
few weeks. 

The function descriptions generally duplicate what is in the
source code. Having them there means that the documentation is
complete in the sense that you can look a function up in the index
and find out something about it. Or you can browse the list of
public functions in board.c and find out what they are without
having to wade through masses of intervening code and statically
declared functions. This seems to me to be useful but if everyone
wants them taken out we can discuss it.

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

Right, at the moment you have two projects (influence and hash) more
urgent than doc revision. Doc revision is a good thing to work on during the
code freeze before the release.

Dan