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

[Trevor Morris]

At 05:31 PM 3/22/2002 +0100, Gunnar Farneback wrote:
>I'd like to hear what other people think about the documentation,
>especially those who have actually read it in an attempt to understand
>the inner workings of GNU Go. We are obviously aware that it's both
>incomplete and more or less out of date in certain areas. Taking that
>into account:
>* 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?

I refer to "The Pattern Code" chapter a lot.  All the time.  It might be worth
considering addressing the Constraint/Action attributes section in a different
way.  Most notably, the attributes vary depending on which *.db file you're
working with, and I don't think how the attributes vary by database are
documented consistently.

Looking through the documentation, again I notice that I refer to "The Pattern
Code" all the time.  The "Analyzing GNU Go's moves" chapter is also very
important.  It's worth considering how to make the documentation most
accessible to would-be tuners, as encouraging tuners is still high on the 
todo list.  Perhaps this would be a good reason to more the "Pattern Code"
chapter closer to the front of the document.

Perhaps a chapter aimed specifically at would-be tuners would be appropriate.
The "Analyzing GNU Go's moves" chapter comes close, but is a bit brief, and
doesn't even reference the "Pattern Database" chapter.  Perhaps a chapter
titled "How to tune" would be in order?  There are some web pages that give
a nice intro to this.  Perhaps adapting them to the documentation would be
in order.

As you may have (hopefully!) noticed, I've not been active here for a couple
of weeks.  Other projects continue to demand my attention, but I do plan
to clean up all of the FIXME that I've marked with "tm:" over the next couple
of weeks.  I hope to have more time in the coming months to do more
tuning and revisit the pattern-based reading code and its offshoots 
(komaster 4 and the tree-based reading).

Cheers,
Trevor