first pass at documenting the new api