Visualizing a complex software application

Question

Question

What is a good way to go about visualizing a complex software application?

Are recommended software applications that can be used for this purpose?

Background

About 3 years ago, I started building a web data mining application. Started out as just me, but has since grown into a project with 5 developers.

I used to be able to keep track of all the parts of the application in my mind, but now it has grown in complexity such that I'm feeling the need for some sort of visual documentation of the application's structure.

I'm not really sure where to go from here. I'm thinking something that looks kind of like a flow chart. But I don't have any background, experience, or formal training in software development on this scale. I have also never served on another team where I could observe someone else architecting a complex application or managing a team. Any pointers in the right direction such as books or resources on the subject would be much appreciated!

Answer 1

I like to use the white boards in my office and draw everything out, this allows for quick editing because you will forget stuff the first time around. White boards are not necessarily needed, you can use paper or whatever on your wall.

Make sure to encapsulate all your objects/variables in a consistent unique shape (it helps later). You also do not need to be detailed in describing variables/functions/classes, get the general concept and let your mind keep the rest.

Once I have it diagrammed out (or at least what fits) I take a picture of it and save it on my computer. Once I have done the entire application I open all the images in an image editor and cut out all the different concepts and what not into individual pictures and save them in a directory.

There are several mind mapping tools and also UML tools for free that let you use your own images. you can build complex flows that you will understand because it's using your images.

Also to address keeping the whole application in my head, I generally just need a reference point to remember whole sections of an application's code, so this really helps with swapping scope.

Answer 2

UML is probably the better-standardized and commonly used tool for this. Some of the diagrams and documents that can be generated in UML can be exceedingly large or complex when used to document bigger systems; however, some of them could be useful if you wish to reach a value/effort balance (i.e. document enough so that you have a good reference point without crossing the line of the documentation becoming more hindrance than help).

I really like the concept of the 4+1 Architectural View Model, which breaks down an architecture into different "views" or perspectives.

Especially for internal documentation purposes, you can determine a granularity and level of detail for the views on which you want to focus and for how specifically you want to document a certain part of your system. I'll try to elaborate more on the different considerations I believe should be kept in mind.

Documentation for different levels

In my opinion, the best approach tends to be to use higher-level documentation for the whole system, and drilling down with more detailed and specific documents when needed.

• You might want to look at System Architecture (or Communication) diagrams for a high-level overview of the components (and using good labelling, this can actually become really useful).

• Also, to look at static structure of the project, Package diagrams are useful (they tell you how your code is laid out). These diagrams, I think, will help you find interactions easily, while reducing the amount of clutter if you have large systems.

• Getting more specific, you might want to generate Activity Diagrams (which are really a lot like flow charts), to specify the different processes in your system. I would recommend doing this only for specific processes in which you need to have a very clear understanding of what is going on. Also, ideally, the processes should not change much after they have been designed - so you can avoid the documentation synchronicity problem.

• Finally, for complex designs, you could look at Class and/or Component Diagrams or a variation of them, where you can really map out the interaction between different pieces of code. Again, unless you have some form of automated generation of the diagram, it tends to be time-consuming to synchronize the code and the documentation, in my opinion.

Think about what you need

• This does not mean "don't do it because it means more work" it means "don't be stupid and do it when you don't need it; it could be painful later on". Wasting time creating documentation that you will not maintain and whose benefits you won't really harness is not what you want.

• Sometimes, what helps most is to draw (I do it on paper, on the desk right next to my computer) simple diagrams that specify how things "communicate". Just creating containers and seeing communication logic can be useful - and this is, in essence what Communication Diagrams do. I would advise to KISS (Keep It Stupid Simple), and focus only on the essential parts when you deem it necessary.