This is first of my experience regarding documenting an already developed project.
Let me first describe the situation which we are going through.
We have developed a system and before a couple of years and currently it is in a maintenance stage.
It is in use in the production for last 1 year. The project is developed in Visual Studio 2003. It is a purely Windows Based Application and developed in VB.Net. The database behind it is SQL Server 2000 and we are using ASP.Net Web Services as middle layer.
Now as the client is going through the inspection of the project, we are now to generate the documentation of the whole project.
Normally, this happens in many of the projects which I see around, typically in our part of world the developers are more inclined to do coding rather then do designing, documentation and planning and then actually doing coding.
Now in this situation, I would like to share with you what we have decided to develop as part of our documentation of the system which might help you at certain point of time in your project. The main part is we are not having enough time right now and we are in a real hurry.
We have decided to prepare the following documents.
1. Database Dictionary
We have found out a very useful tool for generating database documentation. The tool is DBScribe. It is an excellent tool, it automatically generates all the documentation related to all the database objects from the database itself. Right now we are using the trial version in order to check the capabilities. Other nice thing about tool is it is automatically defining the dependencies between the database objects. It generates a chm and html document as output. We are trying to figure out how to insert some of the information in the tool. For example, how to add description of the table and how to add description of stored procedure parameters.
2. Code Commenting
We are using the VB Commenter for generating comments in the code. We are to do two level of commenting in the code. Class level commenting and Procedure level commenting. Following are snippets of what we are going to put as comment in the code.
Class Level Commenting
”’<summary>
”’ [Name] FrontController
”’ [Description] Acts as the initial point of entry/exit into the system
”’ and manages the handling of the request, including invoking security services such as authentication and authorization.
”’ [Reference]
”’ </summary>
”’——————————————————
”’ <remarks>
”’ </remarks>
”’——————————————————
”’ <history>
”’ <creation>
”’ [amita] [anokhi] 12 June 2007
”’ </creation>
”’ <modification>
”’ </modification>
”’ </history>
”’——————————————————
Procedure Level Commenting
”’<summary>
”’ [Name] AuthenticateRequest
”’ [Description] Validates UserID and Password and updates Database by Authenticating Login Request
”’ [Reference]
”’ </summary>
”’——————————————————
”’ <history>
”’ <creation>
”’ [amita] [anokhi] 12 June 2007
”’ </creation>
”’ <modification>
”’ </modification>
”’ </history>
”’——————————————————
”’ Algorithm
”’ Steps
”’ [1] Get Current Context
”’ [2] If Request is of Login from Home page then
”’ [3] Retrieve User Id and Password
”’ [4] If user ID exist in hastable then get its Users Object else goto [7]
”’ [5] If Password is not Correct then goto [7]
”’ [6] Generate Ticket, identity and Principal
”’ Assign it in Context, User object (also in HashTable), Session, Database
”’ [7] If Password or UserId is incorrect then set Users object as nothing and call Invalid Login
”’——————————————————
3. Class Diagram
We are planning to convert our project which is in .Net 2003 to .Net 2005 and generate a class diagram from the IDE itself. Now here I am searching for some more sophisticated automatic class diagram generator tools as generating class diagram from this code manually will be a very time consuming and tedious work. Right now VS-2005 editor is giving some errors while I try to generate the class diagram and also I do not find those class diagrams very attractive.
4. Database Relationship Diagram
This will be similar as what SQL Server generates. We will link up all the tables and then submit the diagram.
Can you suggest me some better and efficient ways of doing this?
As we all know simple basic that we have to do documentation as mentioned simultaneously while we are coding. But now just forget it what the mistakes we have done. its time to do some work on documentation in organized manner.
I suggest to do it by making tools, but we need to take a chance in that case and give proper time to develop it. we all know that we have always across with time constraint, but still i suggest to do it using tool.
we can make a tool that will generate the comment which is in common. for example we can take an example of View, Modal and Controller class. most of the time it is common. if we make a tool such a way that write the common comment in each of the class. so just imagine you can complete the all files in a minute. As we know the commenting for subroutines is always cumbersome for developer as they need to write algorithms, we can not reduce the time for it. but we can always reduce time to write structure.Same thing we can do for stored procedures and user defined functions.
For data dictionary i suggest that is must be done carefully and defined each of the columns clearly then only then it is useful for maintenance else it is just labor.
I think Microsoft Visio is the good option for third and fourth point.
I Hope my suggestions are valuable for you.
Thanking You
Vivek Navadia
Hello Vivek,
Your suggestions are really helpful.
About building tools, we can think of building them. and regarding database documentation tool I think DBScribe is doing good job for the same.
And data dictionary, we will be using Visio most probably.
Thank You,
Kuntal