SitePoint Sponsor

User Tag List

Results 1 to 6 of 6
  1. #1
    SitePoint Guru bronze trophy
    Join Date
    Dec 2003
    Location
    Poland
    Posts
    930
    Mentioned
    7 Post(s)
    Tagged
    0 Thread(s)

    Looking for ideas for easy documentation of database

    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!

  2. #2
    SQL Consultant gold trophysilver trophybronze trophy
    r937's Avatar
    Join Date
    Jul 2002
    Location
    Toronto, Canada
    Posts
    39,220
    Mentioned
    58 Post(s)
    Tagged
    3 Thread(s)
    rudy.ca | @rudydotca
    Buy my SitePoint book: Simply SQL
    "giving out my real stuffs"

  3. #3
    SitePoint Guru bronze trophy
    Join Date
    Dec 2003
    Location
    Poland
    Posts
    930
    Mentioned
    7 Post(s)
    Tagged
    0 Thread(s)
    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.

  4. #4
    SQL Consultant gold trophysilver trophybronze trophy
    r937's Avatar
    Join Date
    Jul 2002
    Location
    Toronto, Canada
    Posts
    39,220
    Mentioned
    58 Post(s)
    Tagged
    3 Thread(s)
    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
    rudy.ca | @rudydotca
    Buy my SitePoint book: Simply SQL
    "giving out my real stuffs"

  5. #5
    SitePoint Guru bronze trophy
    Join Date
    Dec 2003
    Location
    Poland
    Posts
    930
    Mentioned
    7 Post(s)
    Tagged
    0 Thread(s)
    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.

  6. #6
    SQL Consultant gold trophysilver trophybronze trophy
    r937's Avatar
    Join Date
    Jul 2002
    Location
    Toronto, Canada
    Posts
    39,220
    Mentioned
    58 Post(s)
    Tagged
    3 Thread(s)
    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)
    rudy.ca | @rudydotca
    Buy my SitePoint book: Simply SQL
    "giving out my real stuffs"


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •