Please document (1 Viewer)

[oumahexi]

While I agree it is a good idea to have copies of any scripts; relationship maps etc in the documentation for any development I have noticed that many new comers appear to eliminate the absolute foundation of documentation – the reasoning behind it.

Good documentation should include, not only the code behind the system but the reasoning and explanations as to why this code was used and exactly what it is intended to do. For instance:

The client requirement (or specification)
Main concept
Structure
Meta model

I find that taking the approach that the person who will inherit your system may not be completely conversant in the actual workings of your particular profession, ie Law; Education; Medical, leads to a much more concise document, leaving no ambiguity about what you were hoping to achieve from your database.

 

[KenHigg]

Now, now...

I'm guessing you have inherited a db that has no documentation and just needed to vent

 

[oumahexi]

Now, now...

I'm guessing you have inherited a db that has no documentation and just needed to vent

Just trying to be helpful Ken.

 

[KenHigg]

I just had to work on a db a guy did about 10 years ago - What a mess. Had to add a little functionality, tweak a report, etc... I knew the process but he had a bunch of useless bells & whistles that clouded up everything...

 

[namliam]

I knew the process but he had a bunch of useless bells & whistles that clouded up everything...

I am doing something simular, where a process takes 25 minutes start to end.
15 of those minutes are bells & whistles, with the process itself taking only 10

Guess the one who made this wanted to try and do something new???

 

[oumahexi]

Are your bells and whistles documented? My only documentation is a print out of a process that opens a table, looks at the content and closes it again!

 

[KenHigg]

I am doing something simular, where a process takes 25 minutes start to end.
15 of those minutes are bells & whistles, with the process itself taking only 10

Guess the one who made this wanted to try and do something new???

When I make a change, however small, I'm wondering what's it going to break next week or next month...

I'm torn between doing a complete reverse engineer of thing verses just starting from scratch with a new set of business requirements...

 

[KenHigg]

Here's part of my latest pain:

 

[oumahexi]

I'm torn between doing a complete reverse engineer of thing verses just starting from scratch with a new set of business requirements...

I've spent hours in last few weeks documenting which process kicks off which and that's just for one corner of the system. Every time I get a new job to tackle I find myself having to document that part of the system for future use.

This last one is just so bad we just had to start from scratch.

I just don't understand what's the problem with writing down what you've done and why?

 

[oumahexi]

Doddle Ken. Our system links into an external suppliers system to collect "basic information" is converted to speak to our system through SQL Server, then fires the info into Access where the front end can not only be updated by the client, but, should the client wish to, they have an option to "export" a section so they can work remotely, then bring it back and plug it back into the main system...

Not content with that, there are other "external suppliers" who feed us information in a csv file that needs to be imported into the system just once a year (currently working on, no documentation for this process to say what is needed nor where it should go).

Who needs hair anyway

 

[dkinley]

Ken ... looks like the previous really enjoyed that Windows 3.1 windows interface.

I have found that databases grow just like networks ....
The db starts out as a 'need to do a'. Once a boss or something finds out an employee has some sort of knack asks for them to do 'b and/or c'. A year or so later, it is doing 'd thru m' and just like a network it has grown out of control, can't be managed and beyond the skillsets or capabilities.

Here comes people like us that ask, "Do you have the requirements document?" The usual "No" and then the shock and horror with the "1/3 of my bill is going to be documenting."

I agree 6 gabillion percent, I want (and make) flow-charts, decision matrices, external and in-line documentation and most importantly to me why it was done that way and not the other options.

-dK

 

[KenHigg]

...Who needs hair anyway

Try doing without it for a while and you'll see

www.kennethghigginbotham.com

 

[namliam]

My current project is working over 5 SEPETATED databases in different locations of the network, like A export file, transport it to location B, start Datbase C etc.
Some actually open the other database as well to write data to or from it.

Nobody knows this and I have to find out the details literaly! STEP BY STEP in the code.

Last database had ONE sub, mind you ONE SUB when pasted to word was 18 pages 18!!!!! frigging pages, these folks have never heard of comments, functions or structured programming all one big sub...

If someone would actually know what these things actually do, then probably it be faster to rebuild it.... as it is it is one big black box something goes in something comes out that is usefull... period.

 

[oumahexi]

I rest my case. Please document your work so that the next developer can see what they are supposed to be doing.

Thank you.

 

[KenHigg]

I rest my case. Please document your work so that the next developer can see what they are supposed to be doing.

Thank you.

Are you a 'Free' range witch or a 'free range' witch?

 

[oumahexi]

Are you a 'Free' range witch or a 'free range' witch?

Are you trying to get the whole of my profile changed?

 

[KenHigg]

Are you trying to get the whole of my profile changed?

I just wondered if you made a charge for your professional services

 

[Banana]

Documents? We don't need no stinking documents!

For developers who don't develop, I just hire a neurosurgeon to open up their brain. Only had to do it once.

 

[The_Doc_Man]

Banana: Was that brain from "Abbie Normal" by any chance?

I discovered an interesting fact once while managing a five-person development project involving PDP-11 Assembler code. (Try to not choke, folks...) I could tell who wrote a given module by running a little documenter that identified in-line and bulk comment ratios. When you require people to document (which I could do, since I was the boss of the project), they tend to do so along personal preference lines. The method wasn't exact, but it allowed me to characterize every person's code accurately within one or two percent. (I tend to do 60-61% in-line documents and about 30% grouped comment-only lines.)

Then again, for the last 20 years I've worked for the US Dept. of Defense. They claim that we get paid by the hour, not by the pound of documentation, but I think that is a lie. Still, I haven't done a lot of documentation lately. Just dribs and drabs. I'm trying to catch up now, but with the hurricanes shutting down our facility every couple of weeks, it is getting harder and harder to write anything.