July 4, 2003 at 4:19 am
Hey,
I'm at the stage of the project now where I need to start documentation. Documentation has been relaxed in the past, but I want to change that and ensure everything is documented. I have all the objects scripted and saved in sourcesafe.
However, what information would you provide for all of the table objects & security?
Cheers,
Clive
Clive Strong
July 7, 2003 at 1:46 am
Hi Clive,
quote:
However, what information would you provide for all of the table objects & security?
this is a 'depends on' situation.
If you're going to ship a software that remains your intellectual property (meaning you don't ship the source code), I would suggest NOT to provide any information on the database.
But, if this is a software, that was made for one specific customer, and maybe the customer gets the source code, you should (or depending on the contract, you MUST) provide him with all neccessary information about the db. That means, tables, table structures, relations, ...
Now, one can argue if this information has to be a 600 page manual or say 10 or 20 pages.
We have a third-party software here, which was developed just for us. I was involved in the whole db design process, so I knew that part. The final documentation was a 25 page manual containing mostly screenshots and a db diagram). That's all. Although not satisfying, it is juristically bullet-proof.
Cheers,
Frank
--
Frank Kalis
Microsoft SQL Server MVP
Webmaster: http://www.insidesql.org/blogs
My blog: http://www.insidesql.org/blogs/frankkalis/[/url]
July 8, 2003 at 3:08 am
Any other documentation for maintenance purposes, business rules, etc. ?
July 8, 2003 at 5:22 am
Hi Len,
quote:
Any other documentation for maintenance purposes, business rules, etc. ?
sorry, is your post aimed at my comment or at the original?
Cheers,
Frank
--
Frank Kalis
Microsoft SQL Server MVP
Webmaster: http://www.insidesql.org/blogs
My blog: http://www.insidesql.org/blogs/frankkalis/[/url]
July 8, 2003 at 5:56 am
quote:
I'm at the stage of the project now where I need to start documentation.
I have a PM who would break your kneecaps if she heard that you were ready to start documentation AFTER you had built the solution 🙂
quote:
However, what information would you provide for all of the table objects & security?
All of it. The full nine yards. Every security permission on every object. All of the major properties for all the db objects. Tools will automate this process and produce completely accurate documentation of sufficient volume that you can hand it over(*) to whoever asks for it with a smile, say "everything is in there, enjoy!" and be pretty sure they will not come back! However, if anyone ever needs to refer to this forest of documentation, it's likely to be the handful of brief annotations you make here that will probably be most useful, such as adding commentary to design choices within tables that may not be intuitive.
As an example, you can use MS Visio for Enterprise Architects to reverse engineer an existing database and auto generate a report for all db objects showing as much or as little detail as you choose. This comes with .NET Enterprise edition, and won't do the security details I don't think -- but I'm sure there are lots of other free tools with equivalent or superior functionality. Maybe someone knows of something that will produce html page documentation for easy navigation?
However, I find the the most useful documention is that which explains the general design approach. In a db you might identify the key tables and say what they are used for, why they are designed the way they are and - if relevant - who designed them. If you can tie specific tables and stored procedures to the client applications that call them (e.g. ASP page, VB module) so much the better -- I'ld only do this if you are prepared to be thorough though. Also don't waste time explaining things that should be obvious to a competent developer.
Same thing for security ... explain first *what* the chosen policy is trying to achieve and how you've gone about it. Whether your responsible for implementation of your project or not, it might also be nice/arse covering to outline any basic security pre-requsitites not directly related to the database design (e.g. "The PC running SQL Server will not be left in the reception lobby, logged in as Administrator" 🙂 ).
A complementary 'documentation' strategy is to archive a static copy of the db when its through testing, and come to some kind of agreement with the client that this is the product they signed off. You can always reverse engineer the technical details from this at a later point. If the database is changed after it goes into production, the documentation of that process is a separate responsiblity.
----------------
(*) Save the planet, don't actually print it off -- no-one will read it anyway 🙂
July 8, 2003 at 11:50 pm
Hi, a5xo3z1, after reading the two posts it made me think of some maintenance work done awhile back where the business rules got a bit lost after multiple mods and the original developers moved on the greener pastures, documentation not updated, etc.. I think planet115 high lighted what I was trying to get at. Lastly lot of databases have this 'codes' table!
July 9, 2003 at 12:08 am
Hi Len,
quote:
Hi, a5xo3z1, after reading the two posts it made me think of some maintenance work done awhile back where the business rules got a bit lost after multiple mods and the original developers moved on the greener pastures, documentation not updated, etc.. I think planet115 high lighted what I was trying to get at. Lastly lot of databases have this 'codes' table!
I was thinking of 'external' documentation for the customer.
When 'internal' documentation is mentioned, I agree that everything that is possible should be documented.
...but, who is doing this? Who has the time to do so?
Right at the moment we have a total redesign of our mainframe system, which have grown over the last 15 years or so. The people who originally wrote the code mostly don't work here anymore, documentation is at a VERY manageable amount. So most of the time they are trying to figure out what the code is doing. Having figured that out, I guess it's a try and error principle to see what happens somewhere else when they change code in one place. This could have been avoided with appropriate documentation, but in reality when the code runs error free and is it production, and you should document it somehow, you're confronted with the next project.
Cheers,
Frank
--
Frank Kalis
Microsoft SQL Server MVP
Webmaster: http://www.insidesql.org/blogs
My blog: http://www.insidesql.org/blogs/frankkalis/[/url]
July 9, 2003 at 2:54 am
quote:
inreality when the code runs error free and is it production, and you should document it somehow, you're confronted with the next project.
yep, I inhabit that reality too 🙂
However, if it's client work, I think you have a duty to at least explain before work starts that:
1) Without proper documentation, there's a real possibility that the product will not be able to be enhanced/fixed cost effectively in the future.
2) Documentation takes time
3) This time is billable
I hate doing documentation but you can take some of the sting out by doing it as you go along instead of saving it all up for the end.
July 9, 2003 at 3:08 am
Hi planet115
quote:
yep, I inhabit that reality too 🙂However, if it's client work, I think you have a duty to at least explain before work starts that:
1) Without proper documentation, there's a real possibility that the product will not be able to be enhanced/fixed cost effectively in the future.
2) Documentation takes time
3) This time is billable
correct, but most of all - at least here where I live - a missing documentation for the customer of a non standard software (sorry, don't know the right word, meaning difference between buying a M$ product and a software that's made just for one customer) could be the case for a law suit.
That was the case when I was working for a small software company dealing with major german insurance companies. There was NO documentation for the client. No manual or online help. Now, everything went well, but a law suit on this would have been the death blow for the software company
Cheers,
Frank
--
Frank Kalis
Microsoft SQL Server MVP
Webmaster: http://www.insidesql.org/blogs
My blog: http://www.insidesql.org/blogs/frankkalis/[/url]
July 9, 2003 at 4:18 am
Thanks for all the reply's.
Fortunately, the project is not complete and i'm not revisiting. I'm trying to document the objects as I create them. I find that the best way, otherwise I'd just lose track and never do it...
Clive Strong
Viewing 10 posts - 1 through 9 (of 9 total)
You must be logged in to reply to this topic. Login to reply