On documenting the engine

I decided that it would be a good idea to not document the engine with the widespread approach of simply documenting the API, and explaining things piecemeal.  Almost always that stuff is generated from big clunky interleaved function comments that dwarf the code itself and are really painful to read.  There are two short-term reasons I don't want to do it this way.

1. The text editor TextPad can't handle separate docs, I am working with dumb flat text files for the time being, and I really don't want to clutter things up with interleaved doc comments.
2. I never liked API documentation.  They focus on what functions do, and not how to use them or what they mean in the big picture.

Instead, I think that this will be my approach for now ...

1. Explain the framework in detail; this part doesn't change anymore, so this will be like the "key" to the whole rest of the system.
2. Make the code more self-documenting, with stack comments everywhere except where it would be ridiculously obvious or obtrusive, and explain in comments only important things.  Make formatting consistent so simple stack-comment-only glossaries could be generated automatically.
3. Explain things from a bird's eye view in a way that describes the design so you know what you can do with it and where to find what you need.
4. Make glossaries for interfaces.  This part is relatively fixed.
5. Make a cookbook of mini-tutorials for common stuff everyone would want to do.  Deprecate/rewrite tutorials when/if API changes make them outdated.

Subject to revision, but I think I will give it a try and see how it goes.