Click Documentation Tools 1.0

It’s long been a desire of mine to be able to automatically generate Object Model documentation for an Extranet-based store so I’m very happy to announce Version 1.0 of Click Documentation Tools!

This effort all started nearly two years ago as a side project where my goal was to be able to design and document the set of Entity Types that will support a specific site configuration. 

We continually get asked for Database documentation and, as I’m sure you are all aware, each of your physical schemas is unique because it will reflect all of your customer types and attributes. As a result, it’s impractical to maintain a single reference document since it will be inaccurate or incomplete for absolutely every one of you. In addition, a Entity_Relationship diagram of the Physical Scheme will only tell half the story. To get a full picture of how to navigate the “data” it’s also important be understand the available methods on each type. This is why I will continue to argue that, for anyone wanting to configure Extranet-based solutions, it’s the object model that matters more than the database schema.

The goal is to, with the “push of a button”, be able to generate an online Object Model Reference for a given store. In this way, the documentation can keep up with the continued stream of changes caused by ongoing development.

The approach is based upon some work I had done previously in using a UML Authoring tool named StarUML as it was the best free tool I found. It may be old but it did everything I needed it to do. I find designing the initial object model in a UML tool far quicker and easier to adjust than initially implementing it directly into Extranet only for subsequent review to point out the need to make major changes.

In order to route the Object Model design for review and comment, we needed a way to generate documentation. I chose a tool called Doxygen to help me achieve that goal. Now all I needed to do was to marry those tools together and since StarUML is able to generate C# class declarations from the UML and Doxygen is able to generate Object Model documentation from C# Class Declarations, I had my answer.

This worked very well….until the model graduated from preliminary design and was implemented into Extranet. At that point, it became impractical to continue to invest in keeping the UML model in sync with the store. Inconsistencies would inevitably creep in, resulting in documentation that couldn’t be trusted to be accurate. At this stage, the need to be able to generate documentation from the site itself became painfully obvious.

So, to leverage the road traveled to this point, Click Documentation Tools was born. This new tool provides a way to automatically generate C# class declarations for every Entity Type in the store. Once there, Doxygen can do the rest. The result is a consolidated HTML reference of all Entity Types, including inheritance diagrams, collaboration diagrams, attribute and method cross-reference, and hierarchical and alphabetical indices of all types.

Being version 1.0, there are some notable deficiencies. There’s a legacy of Entity Types that are documented with a wide array of formats so not everything that is generated at the moment looks “pretty”. This, however, presents us with an opportunity to work toward a consistent documentation approach for Entity Types, Attributes, and Methods. Now that this tool exists, my hope is the demand for usable descriptions within the configuration will strengthen.

I encourage you to give it a try and let me know what you think. Download the Click Documentation Tools Package to your server and follow the instructions in the ReadMe.htm that is contained in the package file. This is a standard configuration update so should be applied as is to your store via the Administration Manager.

Thanks to Devon and Jacob K. for their contributions to this effort. I hope that this is just the beginning as there are several other aspects of a store’s configuration that deserve to be automatically documented as well. The various scripts that have been authored in several sites to cover specific areas will provide good source material to continue to grow this package.

Cheers!