
Library Writing Realizations - mayoff
http://www.cbloom.com/rants.html
======
scriptdevil
> People will not read the docs.

To try out a new library, I like example code. But for any serious work, docs
are mandatory! I am certain a lot of us have chosen one library over another
because "documentation for B is non-existant". So, yes. If you have 0
documentation for a single file library with 10 functions that is stateless,
probably. But for anything more complex, show me the docs.

> You are writing the library for evaluators and new users.

Again, feels like a poor suggestion despite the next statement that tries to
justify it isn't. In my last job, some choices had been made about a graphing
library just because default pie/bar charts were easy to draw with it. As the
project grew, all hell broke loose because the library did very little to help
customize/extend charts and had close to 0 doc. Even for an open-source
project, read the source isn't a very pleasant suggestion especially when I am
only interested in using the library and not really learning the art of
generating charts.

