ocumenting code seems to be a “thing.”
Support Utopia
Tim Boucher
132

Self documenting products are really cool — but I don’t think we are there yet. Humans need context to understand documents, and machine-readable documentation isn’t always sufficient for human-readable documentation.

A good example is API docs. It’s easy to generate a resource document from your API, but to make it the most useful to users, you might want to include a sample request, a best practice guide and some more context around the different resources you offer. My 2cents. :)