In most of the projects in which I worked, the most common scenario during
the maintenance of a software are the following:
- A certain module is liberated for production (v 1.0).
- With passing of time, alterations are accomplished in this module.
- In most of the "commercial" applications it is common that alterations in
certain modules also alter the model of data. In this point, script files for
updations in the base are created (usually for a DBA).
- The final user needs to have access to what was altered (formally), in the
same measure that the development team involved in the project needs to be
updated about all the alterations. In this point, two new workmanships are
created (usually more refined documents).
The experience that I have been having can be summarized in the following
list of disadvantages:
- The creation of documents and / or files out of the "development
atmosphere"; it is not natural and it demands people are dedicated to this work.
(or it takes a lot of the precious time of the programmers)
- The development team works faster than the dedicated people the
documentation. This turns the documentation obsolete in little time.
- Only the scripts for updating of the database are maintained with certain
The idea here is to show the development of a part (application that
generates documentation) of the alternative solution that I am creating to
outline the subjects exposed above. The illustration below displays which are
the parts of the solution that are to be completed.
The attribute "to mark" the alterations
UpdateDocumentationAttribute is an example and
shows how it can be made to document the alterations. I placed some information
that will be used by the application for version updating. The code that uses
the attribute would be as in the fragment below:
#region Version 126.96.36.199
"SampleAssembly1 - Sumary for developers",
"SampleAssembly1 - Sumary for final users",
See that there are two description types. A technique and another that should
be used to describe to the final users the alterations. A program that generates
documentation can take advantage of this information to generate different
documents, according to the context. In the current version, the documentation
software generates all the information as only document type.
The application that generates documentation
There is not anything very special in the programming of this application.
What is done here is the following:
- To allow to the user to select a period of dates to visualize alterations.
- To allow to the user to select assemblies for which he wants to visualize
- To generate a file XML with base containing the information loaded from the
- To transform the file XML into a document HTML.
Observation: The generation of XML was made to facilitate
the inclusion of new information. It's "extensive" (due to two additional
classes), but the code is readable.
- To increase the filter options (for priority, author, key word etc.)
- To improve the programming of the filter.
- To allow the user to select options for resulting HTML. (XSL used here is
very basic, necessary to research a little more. If you have some format
suggestion doesn't forget to send me a copy. : -)
- To use pagination for very extensive results.
- To transform this application as an add-in for VS.NET. In this case, the
selection of the assemblies will be removed and the information will be
collected now from the solution that's open.
I want to say that I don't know if in the course of time, with a lot of
alterations, the "loader" of the assembly will be prejudiced. I would like to
thank to Ricardo Origuchi for his research work in the transforms using XSL. It
was worth a lot! My English leaves a lot to be wanted, but I am working to
improve this... ;-)