Once again, Daniel has great points. I would just like to add a few: * When documenting API’s, make sure to document preconditions and postconditions, as well

Once again, Daniel has great points. I would just like to add a few: * When documenting API’s, make sure to document preconditions and postconditions, as well an invariants. * Make sure to document guarantees and non-guarantees. Guarantees are things the code must or must not do, where non-guarantees are things that give the code wiggle room and which users cannot rely on, even if they begin to, a la https://xkcd.com/1172/ https://xkcd.com/1172/. * Make sure docs can be tested, just like code. Daniel actually does this for curl docs (later in the post), but he does not list it as a standard. I think it’s a great way to help keep docs up to a high standard.