Best practice for Documentation

[Guest]

We have develoed a complex n-tier windows application (15 months time) with
many contract developers and some in house team members.

But most of the work was done by contract developers. Unfortunately it was
an in house development and things were comminicated by our domain experts
either verbally or by sitting with team members. We don't have much doc now
in hand.

The solutions has serveral complex reports (Crystal Reports 10), Data Access
layers, Business Layer and lot of presentation code.

We have used Stored procedures, views and evey things. it is a quite
professional application.

Now the challenge is how and what to document (Reports, modules ,
architecture etc) that our guys can mainain the application.

Now what to document, how to document and how much detail we need to put is
a big challaenge..?

I need to know what are the recomendations by peers..

Thanks

 

[Bob Powell [MVP]]

First of all I hope you've learned a valuable lesson by realising that
producing an N tier applicatiuon without documentation is a folly.

Secondly, I hope you realise that good documentation isn't trivial. It can
be more demanding than the coding phase and may cost you 60% or more of the
development time.

Lastly, get the VBCommenter Visual Studio Power toy and put inline XML
documentation into your project ASAP. Then use NDoc from SourceForge to
convert the XML into an MSDN style CHM file and resolve never to do that
again!

--
Bob Powell [MVP]
Visual C#, System.Drawing

Ramuseco Limited .NET consulting
http://www.ramuseco.com

Find great Windows Forms articles in Windows Forms Tips and Tricks
http://www.bobpowell.net/tipstricks.htm

Answer those GDI+ questions with the GDI+ FAQ
http://www.bobpowell.net/faqmain.htm

All new articles provide code in C# and VB.NET.
Subscribe to the RSS feeds provided and never miss a new article.

 

[wconniff]

ABB wrote:> Now what to document, how to document and how much detail
we need

I have a couple utilities I developed that may help some, but are
certainly not a complete documentation solution.

The first generates reports directly from your source code. It creates
a list of every procedure, a nested call stack report, a list of all
procedures that call each procedure in the application. There are
separate versions for VB and ASP. Reports are in either RTF or XML
format.

The other tool is a code search that lets you search by language
element, not text. For example, it can find every reference to any
control, e.g., any textbox; any variable type, e.g., any long integer;
or any procedure, e.g., any private function . Results may be saved to
a text or XML file. It is available as a Visual Basic Addin.

 

[Guest]

You really should look into incorporating a case tool into your development
process. Just documenting the code is not enough. You need a full set of
architectural drawings and specifications to really understand how everything
fits together. I recommend Enterprise Architect for Sparx Systems. It's
nearly as full function as some of the big guys but 1/20th the price:

http://www.sparxsystems.com.au/