473,320 Members | 1,823 Online
Bytes | Software Development & Data Engineering Community
Post Job

Home Posts Topics Members FAQ

Join Bytes to post your question to a community of 473,320 software developers and data experts.

how to document a website/database

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?

Thanks,
Shawn
Feb 28 '06 #1
6 11006
Shawn Wilson wrote:
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?

Thanks,
Shawn


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

CH4:D
Mar 1 '06 #2
Shawn Wilson wrote:
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.

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.
Mar 1 '06 #3
NC
Shawn Wilson wrote:

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?


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

Cheers,
NC

Mar 1 '06 #4
NC wrote:
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).


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

Thanks,
Shawn
Mar 1 '06 #5
Ian Collins wrote:
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!


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

Mar 1 '06 #6
CH4:D wrote:
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.
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.
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.
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.
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. ;)


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
Mar 1 '06 #7

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

5
by: Pugi! | last post by:
Hi, I would like to upload office-document (doc, xls, ...) using a form to a website (apache, php, mysql) in a specific directory and if possible insert it into a table (MySQL-db). Is this...
1
by: Doug | last post by:
I have a website I am trying to develop using PHP and Dreamweaver. I also have a library of PHP code which includes the username and password to get in the database. I would like to put this...
1
by: duane | last post by:
Dear Experts: I have a problem. When you enter the website I am working on, wherever you go within the website, the URL address on the website will display: "http:\\..\index.html", whether...
4
by: Otis Hunter | last post by:
I have been given an Access Database which contains a table that has an OLE object field that contains a Word document. That table contains hundreds of records. I would like to find out how I can...
0
by: clintonG | last post by:
I applied aspnet_regsql to SQL2K which was working fine throughout Beta 2 development. After installing Visual Studio and SQL Express RTM my application has blown up. Logging in to the application...
0
by: Ben Holness | last post by:
Hi all, I have a system which allows users to enter a message on a (PHP) website. This message is then put into a (MySQL) Database. A perl script then picks up the message and creates an XML...
6
by: mistral | last post by:
what is correct way open a PDF document in new window use hyperlink? I want show images thumbnails linked with PDF files, when click on thumbnail, PDF will be opened in new window. Some of PDF...
2
by: Wayne Smith | last post by:
Applies to: Visual Studio 2008 Professional Hi everyone, I'm in the middle of creating a website with VS2008 and I'm trying to integrate a user registration/login section on the website but I've...
3
by: DavidPr | last post by:
I made a website for a group of people and they want a visitor counter on it. I don't like hit counters because if the site is dead everyone will know it. But, it's their website. I did an...
0
by: DolphinDB | last post by:
The formulas of 101 quantitative trading alphas used by WorldQuant were presented in the paper 101 Formulaic Alphas. However, some formulas are complex, leading to challenges in calculation. Take...
0
by: DolphinDB | last post by:
Tired of spending countless mintues downsampling your data? Look no further! In this article, you’ll learn how to efficiently downsample 6.48 billion high-frequency records to 61 million...
1
isladogs
by: isladogs | last post by:
The next Access Europe meeting will be on Wednesday 6 Mar 2024 starting at 18:00 UK time (6PM UTC) and finishing at about 19:15 (7.15PM). In this month's session, we are pleased to welcome back...
1
by: PapaRatzi | last post by:
Hello, I am teaching myself MS Access forms design and Visual Basic. I've created a table to capture a list of Top 30 singles and forms to capture new entries. The final step is a form (unbound)...
0
by: CloudSolutions | last post by:
Introduction: For many beginners and individual users, requiring a credit card and email registration may pose a barrier when starting to use cloud servers. However, some cloud server providers now...
0
by: Defcon1945 | last post by:
I'm trying to learn Python using Pycharm but import shutil doesn't work
0
by: Shællîpôpï 09 | last post by:
If u are using a keypad phone, how do u turn on JavaScript, to access features like WhatsApp, Facebook, Instagram....
0
by: af34tf | last post by:
Hi Guys, I have a domain whose name is BytesLimited.com, and I want to sell it. Does anyone know about platforms that allow me to list my domain in auction for free. Thank you
0
by: Faith0G | last post by:
I am starting a new it consulting business and it's been a while since I setup a new website. Is wordpress still the best web based software for hosting a 5 page website? The webpages will be...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.