Lo que busco en "la documentación" de una librería

Acabo de descargar la documentación de una libreria de acceso a datos.
Ustedes dirán, "recien documentandose sobre librerias de acceso a datos?", pues bien, comentemos sobre esto.

Lo gracioso es que, me enviaron un enlace donde mencionaban una nueva librería, y bueno, la propaganda llamaba la atención, pues mejorar la productividad o usabilidad sin necesidad de experticia en SQL, como que te hace pensar un poco, no?

Asi que fuí a la página, busqué información a mayor detalle, nada.
Encontré la seccion documentación, descargue 5 MB en formato chm.

Fiasco.
Total.

Sin animo de ofender a nadie ni considerarme mas de lo que pocos puedan calificarme, considero que "documentación" no tiene que ver solamente con la especificacion de las APIs con la que deberíamos trabajar.

Me explico, "documentación" no se trata de tipos de dato de las funciones y parámetros involucrados.
Considero que si hablamos de documentación, el objetivo de la misma, es hacerse autosostenible, es decir, que no se requiera de alguien mas para comprender la usabilidad del mismo.
Es por ello que en la mayoria de casos no solo se habla de tipos de dato de funciones, sino que ademas, se maneja la descripción de la arquitectura base de las librerias, ejemplos e incluso código fuente (aunque muchos consideren esto, mucho pedir).

Existen situaciones extremas en las que además de la documentación, se entrega el código fuente de las librerias mismas. Pero esto ya es para cuestiones "académicas". Aunque, como muchos de mis amigos dicen, "mas vale que sobre a que falte".

La librería y documentación que originó este breve comentario, ya no viene al caso. Pero si es que llegamos a encontrarnos en el caso de construir una librería de uso comun, y con esto me refiero a mas de una persona.
Pues tengamos en cuenta que lo mejor sería que:
- La librería debería sostenerse por si sola, comentando el propósito de los métodos y sus parámetros, el riesgo a posibles confusiones, disminuye.
- El documento debería contener descripción técnica mas detallada de los componentes a usarse. Un ejemplo claro de todo esto es la manera de documentar la jerarquía DataSet-DataTable-DataColumn-DataRow.
- El documento debería contener ejemplos de uso de los métodos.
- Si es que hubieran proyectos ejemplo, con código fuente documentado, menos interrogantes quedarían.

Krysztof Cwalina posteó hace unos meses sobre algunos lineamientos que deberían tomarse en cuenta. Aqui el post y el documento adjunto, el cual es un minibreve resumen del excelente libro que publicó hace un par de años.

Bueno, de momento solo queda dejar abierto el post a todas las recomendaciones que usted, amigo lector, considere conveniente.

Saludos[at]Casa