Re:Making world-class docs takes effort
by ghoward on Monday September 06, 2021 @03:05PM
(#28436883)
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/.
* 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.
* 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/.
* 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.