how to document a website/database

Do you have a question? Post it now! No Registration Necessary.  Now with pictures!

Threaded View
I've got a fairly complex LAMP database and website that have grown,
I'll say, "organically".  That is, without much structure or initial
planning.  I'm finding it hard to keep all the different relationships
straight as I continue to develop it.  With that in mind I would like to
document the project, but I don't have a lot of experience with
documenting and charting, etc. (I vaguely remember flowcharts and Gantt
diagrams from a brief programming course).  I would also like to do this
as a visual aid for potential investors.

Could someone point me to a good resource for learning about this kind
of thing? It's hard to separate the wheat from the chaff when googling.
Also, can anyone recommend the types of documents I should be
considering and any good programs for making them?


Re: how to document a website/database

Shawn Wilson wrote:

Quoted text here. Click to load it


This may not be a practical approach but at least it gives you
something start with. I also do this kinda thing although that isn't my
job anyomre these days. I usually just put a description on each table
with the following things in its description: What it is, what data is
stored (fields) and how is it stored (data types). Since you grow your
database "organically" it would be a good idea to add to the
description which tables reference it as well. If you're using linker
or lookup table you can just describe the foreign keys there and where
it goes.

For diagramming, we use MS Visio or just Powerpoint will do. I suggest
you research on symbols with entity relationships on tables. There's a
standard set of symbols there. If your main purpose is merely for
presentation, then you can just draw lines and arrows pointing to the
table relationships since non-db folks won't care what these symbols
are. They just want to see how the whole thing fits in.

You don't need a good resource, it's just a matter of developing good
practices. Your people will appreciate it in time as you learn to
develop good documentation skills. It's not something you read but
learn through experience. ;)

Hope this helps.


Re: how to document a website/database

CH4:D wrote:

Quoted text here. Click to load it

I'm pretty good about commenting my code, but it never occurred to me to
comment in the db itself.  That's a good idea.

Quoted text here. Click to load it

I think I've got both of those kicking around here somewhere. I'll check
them out.  I've been looking into the ERD symbols.  We'll likely have 2 sets
of documents - technical (for me an in case potential investors ask for a
"technical audit") and overview.

Quoted text here. Click to load it

I like to go through written resources when I'm first learning things, then
adapt them to suit my needs.  I find there's less reinvention of the wheel
that way.

Thanks for the reply,

Re: how to document a website/database

Shawn Wilson wrote:
Quoted text here. Click to load it
One approach is to develop the site test first and use your unit tests  
as the documentation and requirement definitions.  Works well with  
'organic' site development!

Ian Collins.

Re: how to document a website/database

Ian Collins wrote:

Quoted text here. Click to load it

Thanks, I'll consider that, though the intention is to get a bit more
professional on the management side of things.  I want to learn this stuff for
future projects in order to avoid some of the pitfalls I've run into.


Re: how to document a website/database

Shawn Wilson wrote:
Quoted text here. Click to load it

Consider creating three documents:

1. Functional specification -- a document explaining what your
   application is supposed to do.

   Read "Painless Functional Specifications" by Joel Spolsky:

   (Yes, in that order...)

2. User's manual -- a document explaining how a user is supposed
   to get the application to do what it's supposed to do.

   You may want take a look at "User Interface Design for Programmers"
   by Joel Spolsky:

3. Developer's manual -- a document explaining what the application's
   architecture is, what different pieces of code do, and what the
   application's data model is (e.g., what the database tables are used

   for and what the fields in those tables store).  


Re: how to document a website/database

NC wrote:

Quoted text here. Click to load it

I just read half of the first one.  It appears to be pretty well written.
I'll give those a read.


Site Timeline