Documentation Strategies
-
I am currently doing the technical design for a system that will make use of a number of SQL Server stored procedures. The depth of documentation required throughout the system is high (by my normal standards anyway!), and I'm wondering if anyone knows of, uses or recommends a template for documenting stored procedures.
The format I'm working with is:
Stored Procedure Name
Description: Plain English description of what the procedure is aiming to achieve (within the context of the application)
Parameters: Input parameters - name, type, description if not obvious
Output: Any output parameters
Returns: The make up of any returned recordset.
What I'm really struggling with is the 'level' (i.e. style/content) of language to use with the "Description" and "Returns" sections. Get too technical and you might as well just build the TSQL and let that stand on it's own ... too abstract and it is of no use to the developer to work from.
I'm sure that such documentation must be written by developers and architects every single day, so I'ld be grateful to benefit from anyone's experience (positive or negative) in this matter. (or any useful links obviously)
Cheers
Will
-
Hi,
I been toying with the idea myself. I need to re-format all of my documentation as, basically it sucks.
For SP's, I plan to document all of the criteria you have specified. I also document where the SP can be called from.
Again, the actual format you have defined is the same as what I defined for my needs.
Also, ensure you have helpfull comments in your SP code itself. These can be invaluble.
Clive Strong
-
Usually I do something similar to what you have and be basic about it at the header of the SP. Then on each section and sometimes lines I make more specific notes as to what is happening and why.
Ex.
If Month(@DateUse) >= 10 --Check To See if Date is Oct, Nov, or Dec
BEGIN
Set @TimeChg = '10/31/' + Cast(Year(@DateUse) as varchar) --Use Oct 31 as strt Point
END
ELSE
Set @TimeChg = '4/1/' + Cast(Year(@DateUse) as varchar) --Use April 1 as start point
"Don't roll your eyes at me. I will tape them in place." (Teacher on Boston Public)
-
I'm currently using the format of:
/******************
Name: s_MyProc
Parameters: @p1,int,in,This parameter does ...
Purpose: This proc does ...
Background: The reason we needed this proc was...
Example: EXEC s_MyProc 1 (this would return...)
Created By: me (my@email.com)
Created Date: 1/1/2002
Modified By: somebody else (somebody@there.com)
Modified Date: 2/2/2002
Modification Notes: Modified it because ...
******************/
I don't necessarily have a line item for what is returned by the procedure, although that might be a good idea. I use the background section for the plain english description of all that and any background information on the procedure. It's amazing how many times I've gone back to an application a year later and can't for the love of money figure out why I did something a certain way. Then I change it and break something...THEN, I figure out why I did it that way. This section basically tries to help me with that issue.
The Modification Notes are helpful too. Sometimes on some procedures you may have a bunch of modifications, and it's better to have extra text telling you what changed, when it changed, and who changed it. I also like to add the email address of the creator and modifier. Seems like on some teams it doesn't take too long before you forget who dk was, or just which Jim changed it.
The other consideration I've taken with the comments of the procs is that if you keep all of your comments formatted a particular way, and enforce that template for all of your developers, you can actually build a tool that will parse through them and create a documentation tool. That tool can also find procedures where your developers didn't follow the standard.
HTH,
David Sumlin
-
I try to enforce a scheme like that of David. Developpers always argue that it is a lot of work, filling up all the fields. (They obviously have never had to cope with a badly documented project being shoved up their throat
.)The description part should contain plain English, that relates to the objects and terminology for the project. Certainly nothing technical.
And as a side note, I would advise you to try to keep a similar scheme for documenting the other programming languages in your project. That makes it easier for the developpers to get habituated to the commenting block.
-
Thanks for all your comments. I think we have a concensus!
I certainly agree with the idea of having fixed templates throughout all languages (as far as possible) and documenting any modifications with developer initials, date and scope/reason for change is an absolute must.
I'm still struggling to find the "voice" of my plain english descriptions though. The purpose of the documentation I am currently writing is that it could be used by a developer to build the procedure, without being too prescriptive about how this is actually achieved. In this case it's likely that the developing work will fall to me, but you never know, I may get transferred to the Caribbean at a moment's notice* and leave it all to someone else 🙂
The idea of using tools to validate documentation is a very good one ... and one that I think has been taken up pretty well within the .NET IDE. I'm thinking about writing a web front end to allow stored procedures to be defined (very much in the format agreed here by all) and grouped. The s.p. definitions would be stored in XML and so could be easily manipulated to generate paper documentation in different formats, as well as to create stubs for the s.p. itself.
Thanks again.
Will
* - I much prefer this to the "You could be run over by a bus" line of argument.
-
Great to be of (some) help. But I would like to comment on your last post.
In my opinion you are mixing up two different things. First is commenting the code and the second is writing a technical design for the database.
The code comments, should not be descriptive of the way how an SP works (internally). The code itself (with embedded comments, of course) have to do that for you.
This is a job for the 'developper'.
But if you are writing a technical design, that will be implemented later on, you could write some kind of pseudo-code version of the stored procedure. This is the task of the 'analist'.
In general, I try to have my pseudo-code as the comments in the real code.
And in the case where you are both analist and developper, it looks like double work, unless you get to go to the Caribbean (why not me????
). -
Like the XML idea by the way.
If you ever have a framework that you would like to share with us
-
BI Documenter might be what you are looking for. It does SQL Server and Analysis Services databases and supports SQL Server 2000 and 2005.
.)
).Viewing 9 posts - 1 through 8 (of 8 total)
You must be logged in to reply to this topic. Login to reply