Embeded Documentation Templates

Notes

Extreme programming style places emphasis close association of documentation with developed code. This means that that developers need to provide documentation through commenting the code.

Visual Studio provides for documentation and documentation generation within compiled code. Each class, or class member can be annotated with specific tags and then the project can be compiled to generate an XML file containing documentation of members. Unfortunately there is no support for code that is either non compiled (e.g. database projects) or compiled within IIS (e.g. web pages)

To fill this gap we developed a set of templates that we embed into our code and which are subsequently used to automatically generate documentation. An example of such code may be documentation of SQL Server Table definition which contains the intention of the table, intention of each attribute and list of changes. This allows automatic generation of Data Dictionary if such a document is indeed required.

The remaining details such as dependencies, primary and foreign keys can be programmatically extracted from SQL Server and requiring developers to populate such details would only lead to discrepancies between code and documentation.

It can be argued that also change details can be extracted from the Source Control system. We find however, that on many occasions multiple pieces of code are checked in together. So we decided to maintain list of changes manually within code itself.

The available templates are continuously in use so please note that we will modify them without notice. If you want to use them please download them to your server.

Documentation templates

Description Download
.NET aspx pages.
SQL Server Contract.
SQL Server Function.
SQL Server Message.
SQL Server Queue.
SQL Server Service.
SQL Server View.
SQL Server Stored Procedure.
SQL Server Table.