try to back up my opinions with some evidence but of course there will be differing thoughts. My opinions are based on over two years of maintaining relatively popular Ruby libraries, as well as being a full-time Ruby dev for over five years.
a request, I don’t want to see a SocketError pop up. I didn’t make a socket, how did I error? Libraries should catch their exceptions, wrap them in their own, and expose them in a documented way. More on this later.
the norms. * Ruby has been around for a long time now, we’ve got our conventions. * Helps people pick it up faster. * Gives users that “it just feels right” feeling. Don’t try to be cool. I’m not going to spend much time on this section because this is generally the part that people get right, because they’re used to working with Ruby already and this is what they focus on. Plus, during the talk I’m super crunched for time, so I had to move on.
option • Use something custom * stdout/stderr: Tempting, but extremely annoying and can cause crashes if pipe is closed. * “debug” option is fine, but don’t require it. Sometimes I want debug logging, but not other debug behavior. * log4r may not be the best, but the last thing we need is more fragmentation.
off docs until the end so your lib isn’t changing much anymore, but documentation is SO BORING that you’ll end up hating yourself. * Write it as you go (like tests). If the library changes, then you’ll have to change docs, so there is more work, but at least you’ll have the docs at the end. * Example: Vagrant 0.1 docs pushed off until the end, took me 2 weeks to write them. Really burned me out. More work, but less pain.
the same repo as the code. * Use a branch, won’t ever be merged into master, so clean it and just keep it going. * Makes it easy to contribute. (Pull requests!) * Can see “point-in-time” documentation for specific versions