API guidelines doc

This is super in-progress. A lot of this information is sort of tribal knowledge, but I wanted to get it in out in the open and us on the same page.

This should give us somewhere to look when we're like "how should I name that method/event?", or "how do I doc a method that takes a callback that takes an options hash."
Event naming is hard. The other day @nathansobo said something like "I dont like how our events are named", and we talked a bit about naming.

Right now they are all past tense: `contents-modified`, `markers-updated`, etc. and they are pretty consistently named. We talked about how preemptive events should be named. We came up with `will-insert-text` and `did-insert-text`. If we went down that route, then all the events would need to be renamed to be in this format: `did-modify-contents`, `did-update-markers`. I dont think we want to rename all the events (I dont, man, I dont). But I would like to have a story for preemptive events like `will-insert-text`.

Thoughts?