Documenting V3 internals

[Rich Churcher]

Gabriel Dos Reis <Gabriel.Dos-Reis@cmla.ens-cachan.fr> writes:

[ snip ]
> Users should not concern themselves with the library's internals -- all
> they need is the library's observable behaviour.  Users have no
> business in knowing how we actually provide the services contracted
> through the interfaces.  As such, there is no point in providing users
> with any documentation mentioning which internal files do which jobs.

Won't we end up with a duplication of existing standards documentation
(Josuttis, the ISO document, etc.) in that case?  I guess I saw this
as an opportunity to provide some detail on the V3 implementation, but
perhaps I'm barking up the wrong tree.  

The idea of not providing as much detail as is available on library
internals strikes me as an attitude more suited to a commercial
project than an open source effort.  Of course I say this as a
bystander with little experience and no credibility :o)  However, I had
imagined that documentation might help new developers familiarise
themselves with the source, or direct library users in troubleshooting
efforts.

Let's put it another way - what areas of the project do you see as
being poorly documented at this time, and what kind of documentation
would you provide to correct the problem?

-- 
Cheers,
Rich.