I have a web application based on mysql and the database structure keeps growing as new features are added. I would like to find an easy way of writing a documentation for my database. I'm not so much in need of a graphical representation or diagrams, I want to be able to describe some tables and fields with text. Do you have any practices to recommend? So far I have a few ideas (and questions) but I don't know if there isn't a better way:
keep documentation in a html file and edit it with some wysiwyg editor like Kompozer. I could have one file for all tables or a separate file for each table - I don't know which would be better.
document tables and fields in mysql schema itself, however sometimes I need a longer description and mysql comments are awkward
use a dedicated software for documentation - can you recommend something? I'd prefer something free since I don't have high requirements
to get me started I might use a program that would reverse-engineer table definitions in a readable file and then I could work on that. I know SQLYog can export an HTML file which I could later edit
Any ideas are welcome!
I'm more interested in some personal experiences, what kind of documentation someone has found most useful. Most of the software is for creating diagrams, designing database, etc. I'm looking for a simple tool to store textual descriptions for fields and tables.
if it's mysql, you can simply use the CREATE TABLE statements as your documentation, which has the added benefit of being "live" (i.e. unlike other documentation, it will reflect the exact table structure even after changes are made to the table)
mysql gives you an opportunity to add a comment to each table and each column, and that, together with the simple SHOW CREATE TABLE command to display the table structure, should satisfy your requirement
Unfortunately, comments can't be longer than 255 characters, which is very limiting for anything but the simplest descriptions. And besides, editing comments is very inconvenient in many mysql tools like phpmyadmin or sqlyog because they provide a very small input box.
oh, that's simple... get a tool which provides a bigger input box
as for 255 being insufficient, i'm afraid i really can't help you there
the essence of good documentation is to be concise!!
(i can't believe i have to say this in the age of twitter)