Post History

Source: https://writers.stackexchange.com/a/12629
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

It depends on your audience.

Blessed Geek suggested UML enumeration, but this assumes that the users understand UML. Your question shows that you know technology well enough to know the capabilities of your users.

Writers often use Javadoc or Doxygen to generate API documentation because those tools easily generate new docs when the API itself changes. Updating the documentation as the code changes is useful when the code is changing a lot. For your database schema, however, that may not be a consideration. Schemas don't change very often, and when they do, they're usually added to. The technical impact of deleting or modifying fields in a database is large.

It's easy enough to print out field names and types from a database using its tools. From this printout, you can produce an HTML table that has a blank column where you can provide more documentation about the field. An image that's something like a simplified UML diagram can help readers understand how the tables of the database are related to each other. If you want some additional ideas, take a look at [Contacts Provider](http://developer.android.com/guide/topics/providers/contacts-provider.html) in the Android documentation.

Original score: 2