For over a decade I have been a devotee of one of the world's most
enduring and successful free software projects; and, like most such
projects, its documentation is inadequate. It suffers from the common
problem that it tells you what commands you have available; but you
are left baffled as to when each one is appropriate, why you might
want to use many of them, or even what some of them do.

This situation is so severe that the user community are reduced to
writing documentation for each other - both basic introductions to the
software and detailed accounts of particular aspects of its operation
- but the development team are unwilling to include any of this
material in the main distribution. I have written one substantial
piece of this documentation, and plan to write more.

However, even with this assistance, the program's fiendish complexity
means that an expert user of the program is nearly always familiar
with considerable portions of the source code - a nontrivial
undertaking, since the program is of similar size to the Linux kernel
- and extracts from the source are a frequent sight in discussions of
the program's behaviour.

I think that a book covering all aspects of the program would be
overly ambitious, and hence any ORA work on the subject would assume
that users have at least read the project's own documentation (and so
are familiar with the 'what', if not the 'why'). Instead, one could
start with a more general discussion of how to use the program
effectively, talking about basic principles of its operation; then
talk about specific aspects that often trouble users; and finally
discuss the layout and general style of the source code. I would not
envisage readers reading the second and third sections linearly,
especially since the second section would necessarily contain short
source code extracts.

The usual publishers of books in this field have been unwilling to
tackle this subject; so I hope I can persuade you of the necessity of
"Understanding NetHack".