Re: Documenting V3 internals

[Gabriel Dos Reis <Gabriel dot Dos-Reis at cmla dot ens-cachan dot fr>]

Rich Churcher <churcher@ihug.com.au> writes:

| 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? 

No.  For several reasons.  The ISO document is written in an esoteric
language and is not intended for tutorial not suited for a "howto"
style.  Nico's book is great but doesn't cover every anyone ever
wanted to know about how to use V3 efficiently. etc.

| ... 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.  

Sure, there is room for documenting V3 and your offer to contribute
documentation is wellcome.  But I do not agree with the idea of
providing users with documentation about V3's internal.  

| 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. 

That is a silly argument.

Not just because it is open source means we should overlook sound
software engineering practices.  Telling users how we happen to
implement class X at YY:MM:DD:hh:mm:ss doesn't buy them and us
anything at all.  That idea violates the principle of leats commitment
we're contracting through interfaces; it violates encapsulation.  In
the end, implementors and users will be locked into a particular
implementation.  All users need to know about the library is its
interface semantics. 

| ... 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.

Well, there is a difference between documenting V3 for V3 developpers
and documenting V3 for V3 users.  I'm arguing against the idea of
providing V3 users with its internal implementation details.  Of
course, I don't object to documentation targetting V3 developpers, if
done properly.

| 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?

From the top of my head:
1) mini howtos to moving from v2 to v3.
2) installation configurations
3) howto to use locales, etc.

That is more useful than telling users how we internally implement
things.

-- Gaby