add write/1 function.
add notes about returned data structure.