how to document a website/database

**CH4:D** · Mar 1 '06, 03:15 AM

Re: how to document a website/database

Shawn Wilson wrote:
[color=blue]
> I've got a fairly complex LAMP database and website that have grown,
> I'll say, "organicall y". 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?
>
> Thanks,
> Shawn[/color]

Dude,

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 "organicall y" 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.

CH4:D

**Ian Collins** · Mar 1 '06, 04:15 AM

Re: how to document a website/database

Shawn Wilson wrote:[color=blue]
> I've got a fairly complex LAMP database and website that have grown,
> I'll say, "organicall y". 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.
>[/color]
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.

NC · Mar 1 '06, 04:55 AM

Re: how to document a website/database

Shawn Wilson wrote:[color=blue]
>
> I've got a fairly complex LAMP database and website that have grown,
> I'll say, "organicall y". 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?[/color]

Consider creating three documents:

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

Read "Painless Functional Specifications" by Joel Spolsky:

Painless Functional Specifications – Part 1: Why Bother?

http://www.joelonsoftware.com/articles/fog0000000036.html

When The Joel Test first appeared, one of the biggest sore points readers reported had to do with writing specs. It seems that specs are like flossing: everybody knows they should be writing them, …

Painless Functional Specifications – Part 2: What’s a Spec?

http://www.joelonsoftware.com/articles/fog0000000035.html

(Have you already read part one? If not, that’s here .) This series of articles is about functional specifications, not technical specifications. People get these mixed up. I don’t know…

Painless Functional Specifications – Part 3: But… How?

http://www.joelonsoftware.com/articles/fog0000000034.html

Now that you’ve read all about why you need a spec and what a spec has in it, let’s talk about who should write them. Who writes specs? Let me give you a little Microsoft history here. …

Painless Functional Specifications – Part 4: Tips

http://www.joelonsoftware.com/articles/fog0000000033.html

OK, we’ve talked about why you need a spec, what a spec has in it, and who should write them. In this fourth and final part of the series I’ll share some of my advice for writing …

(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:

Controlling Your Environment Makes You Happy

http://www.joelonsoftware.com/uibook/chapters/fog0000000057.html

Most of the hard core C++ programmers I know hate user interface programming. This surprises me, because I find UI programming to be quintessentially easy, straightforward, and fun. It’s easy…

Figuring Out What They Expected

http://www.joelonsoftware.com/uibook/chapters/fog0000000058.html

When a new user sits down to use a program, they do not come with a completely clean slate. They have some expectations of how they think the program is going to work. If they’ve used similar…

Choices

http://www.joelonsoftware.com/uibook/chapters/fog0000000059.html

When you go into a restaurant and you see a sign that says “No Dogs Allowed,” you might think that sign is purely proscriptive: Mr. Restaurant doesn’t like dogs around, so when he…

Affordances and Metaphors

http://www.joelonsoftware.com/uibook/chapters/fog0000000060.html

Developing a user interface where the program model matches the user model is not easy. Sometimes, your users might not have a concrete expectation of how the program works and what it’s supp…

Consistency and Other Hobgoblins

http://www.joelonsoftware.com/uibook/chapters/fog0000000061.html

The main programs in the Microsoft Office suite, Word and Excel, were developed from scratch at Microsoft, but others were bought from outside companies, notably FrontPage (bought from Vermeer) and…

Designing for People Who Have Better Things To Do With Their Lives

http://www.joelonsoftware.com/uibook/chapters/fog0000000062.html

When you design user interfaces, it’s a good idea to keep two principles in mind: Users don’t have the manual, and if they did, they wouldn’t read it. In fact, users can’t r…

Designing for People Who Have Better Things To Do With Their Lives, Part Two

http://www.joelonsoftware.com/uibook/chapters/fog0000000063.html

When the Macintosh was new, Bruce “Tog” Tognazzini wrote a column in Apple’s developer magazine on UI. In his column, people wrote in with lots of interesting UI design problems, …

Designing for People Who Have Better Things To Do With Their Lives, Part Three

http://www.joelonsoftware.com/uibook/chapters/fog0000000064.html

One of the early principles of GUI interfaces was that you shouldn’t ask people to remember things that the computer could remember. The classic example is the Open File dialog box, which sho…

The Process of Designing a Product

http://www.joelonsoftware.com/uibook/chapters/fog0000000065.html

We’ve talked about the principles of good design, but principles only give you a way to evaluate and improve an existing design. But… how do you figure out what the dang design should b…

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).

Cheers,
NC

**Shawn Wilson** · Mar 1 '06, 06:55 PM

Re: how to document a website/database

NC wrote:
[color=blue]
> Consider creating three documents:
>
> 1. Functional specification -- a document explaining what your
> application is supposed to do.
>
> Read "Painless Functional Specifications" by Joel Spolsky:
>
> http://www.joelonsoftware.com/articl...000000036.html
> http://www.joelonsoftware.com/articl...000000035.html
> http://www.joelonsoftware.com/articl...000000034.html
> http://www.joelonsoftware.com/articl...000000033.html
>
> (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:
>
> http://www.joelonsoftware.com/uibook...000000057.html
> http://www.joelonsoftware.com/uibook...000000058.html
> http://www.joelonsoftware.com/uibook...000000059.html
> http://www.joelonsoftware.com/uibook...000000060.html
> http://www.joelonsoftware.com/uibook...000000061.html
> http://www.joelonsoftware.com/uibook...000000062.html
> http://www.joelonsoftware.com/uibook...000000063.html
> http://www.joelonsoftware.com/uibook...000000064.html
> http://www.joelonsoftware.com/uibook...000000065.html
>
> 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).[/color]

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

Thanks,
Shawn

**Shawn Wilson** · Mar 1 '06, 06:55 PM

Re: how to document a website/database

Ian Collins wrote:
[color=blue]
> 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![/color]

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.

Shawn

**Shawn Wilson** · Mar 1 '06, 07:05 PM

Re: how to document a website/database

CH4:D wrote:
[color=blue]
> 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 "organicall y" 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.[/color]

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.
[color=blue]
> 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.[/color]

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.
[color=blue]
> 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. ;)[/color]

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,
Shawn

how to document a website/database

how to document a website/database

Comment

Comment

Comment

Comment

Comment

Comment