More documentation for IO

fixes #630 
Can you also highlight what happens if an error is thrown during writing?