Open Source .NET Development [Electronic resources]

Documentation Tools

As a rule, I know that all developers love documentation. That is, they love it when they are taking over a project and want to quickly understand the concepts of the design. Unfortunately, most developers and development teams push off documentation until the very last minute. During the frenzy of a software release, most often the documentation is neglected and never completed. In my experience, projects go much more smoothly when the documentation is kept up-to-date incrementally with the code. While I am a firm believer in comments in the code, the most helpful documentation I have seen is usually a document describing the overall intent of the developers' design. Are you using Web services or remoting? Is the project using Single Call or Singleton design patterns? Of course, this can all be determined by looking at the code, but that is not as useful as a design document. The final and perhaps most important use of documentation is to communicate the author's intent. I sometimes find that a design document is very solid while the implementation is not. Documentation helps convey the intent, even if the code does not match the design.

Open Office

Open Office (Figure 3-6) is an Open Source project available at http://www.openoffice.org. Open Office contains a word processor called Writer, a spreadsheet program called Calc, and a presentation tool called Impress.

Sun Microsystems also repackages a version of Open Office called Star Office in which they add a database to round off the office suite. These tools can read and write to Microsoft Office files and contain very similar functionality. Figure 3-6 shows Open Office on Mandrake Linux (http://www.mandrake-linux.com), but the project also has a Windows port available. Open Office's Writer application is great for creating first-class documentation.

ArgoUML

Not long after starting in software and documentation, I began to think, "Wouldn't it be great if all the diagrams that are drawn in documentation were standardized!" Then I ran into UML. For a good book on UML, see:

UML Distilled , Second Edition by Martin Fowler and Kendall Scott,

Addison-Wesley

UML is not the only way to go, but I do find it helpful if followed loosely with a little improvising here and there. One thing I dislike about most UML editors is that they restrict what I want to do in my diagram. I am not a supporter of following UML to the tee and then allowing the tool to create my code. I just want to use UML to display my intent in a design document. For this, I like the ArgoUml Open Source project from http://argouml.tigris.com. This Java program, shown in Figure 3-7, runs on both Windows and Linux.