Architectural design documentation strategies

Question

I am trying to document a software project up to the current stage. The readership would involve myself (in a future time), other developers (currently and in the short-term future), as well as end users. Therefore, the documentation has descriptions of design requirements, architecture/design (data structures, architecture, user interface, procedural design), technical documentation, and end user instructions. The documentation is mainly produced in order to provide some historical record. Currently, it's a team of 2 people working on the project, although it could involve more people in the short-term future as more features from other people's projects are added to this project.

What I'm having trouble is with the architectural design documentation (http://en.wikipedia.org/wiki/Design_document). While I have tried using doxygen to create some type of data flow diagram, it hasn't been easy. Are there any tools that would make it any easier to generate data flow diagrams from C++ code, or would this be a case of drawing manually on Microsoft Visio? Thanks in advance.

Answer 1

You can download a trial of Visual Studio Team Suite which includes the architect edition components.

Answer 2

Any low level diagrams automatically generated from source code are going to be useless. They'll be more obscure than your code, have a messy visual layout, and soon be out of date. Future developers will distrust them and look at the code instead, so you're better off investing the extra effort into refactoring your source code (ie, to use self-explanatory names, have a class structure that represents your problem domain cleanly, and so on).

It is worthwhile to create good javadoc or doxygen comments and keep them up to date: many people find these quite useful.

High-level diagrams also are valuable. Read Martin Fowler's UML Distilled and learn the UML notation. Then use Viso or another graphical editor to document just the parts of your software that would be helpful for future developers. Don't waste time making the diagrams "complete" and perfect, just focus on what will help other developers the most.

Answer 3

Before a tool can document your code it would have to read it.

Reading your code is also known as "reverse engineering" it.

Code can be reverse engineered by various tools, which can then create UML diagrams of that code. Sadly when I tried this even only a few years ago I found that some tools, which do a great job at reverse engineering C# for example, do an imperfect job at reverse engineering legacy C++ (because C++ is more difficult to parse, and supports non-OO global functions, etc.).

Still you can find lots of tools by using Google with the terms "reverse engineer" or "roundtrip" with "C++" and "UML" or "diagram".

Microsoft have promised improved C++ tools, but I don't know what the timeline for that is.