Do not merge: Plain text description of the API

[mwcraig]

The intent of this is not to be merged. The intent was to do two things:

• Pull in some of the very recent API changes or proposals (Markers API refactor #145 and New offset_by with new API #140) into the rest of the API description.
• Provide a (perhaps) easier format for discussing the API that is completely separate from implementation.

[pllim]

But... but... our code is self-documenting...

[mwcraig]

Agreed -- that is why this isn't intended to land in the repository ever. I thought it would be helpful to talk about any remaining API issues/questions before deciding how we move forward with that API (ABC or protocol or...).

Put differently, I wasn't sure whether to update #126 or #142 so I copy-pasted into a separate doc 😬

[pllim]

Both @gpdf and @astrofrog did not like my approach with #126 , so maybe #142 is the better way to go. 🤷