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

[Inge Wallin]

Gunnar wrote:
> Some observations regarding the structure of the documentation:
> 
> 1. There are almost more details than overview in overview.texi. I'd
> like this chapter to briefly introduce the various techniques being
> used in the engine, with lots of references to later chapters.

I agree.

> 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 agree vehemently.  For one thing, it is a waste of paper, and for
another such lists tend to get out of sync with the code in pretty
short time.
 
> The real problem in my opinion is that chapters 6 (API) and 7 (SGF)
> are completely out of place. For the understanding of the engine these
> are very auxiliary and would come more naturally towards the end of
> the documentation.

The original thought of placing them there is that the chapters should
be ordered by how much depth they provide.  There are roughly three
sections as it is now:
1. The user documentation.
2. The documentation for those who want to use the engine.  This would
   be mostly people who want to create a GUI.
3. The programmers guide providing in depth information about the
   internals of the engine.

What you mention above is what I think is section 2 above.  However,
if you think that more people are interested in the internals than in
the interface, then by all means change the order. I have no problems
with that.

> Chapter 8 (board) is placed okay but the title (The Board Library) is
> strange. What's important in the chapter is to discuss how the board
> is handled. That there happens to be a separate library for the board
> code is hardly a major point.

It is also important to show how to use board code.  That is the
reason for the title.  Remember that we not only have users and engine
programmers. We might also have programmers that want to use our code
without enhancing it internally.

> Chapters 9 to 17 all give details about various modules. The ordering
> here is maybe not critical but I think it might make some sense to try
> to do it bottom-up. If so, chapter 9 (move generation) should be
> postponed.

I think top-down is a better approach.  I think it makes it easier to
get a general understanding.

        -Inge