Most of the serious developers first create at least some documentation about the software they are going to develop. One way to do it, is to take a piece of paper and a ball pen, or even better, a pencil and an rubber. This is a good way to start, but what happens with this documentation after some time? Even few weeks from the start, they end up in a trash can, and then, your software blueprints exists only in your memory and in the source code.
Now imagine this scenario (which actually often happens, when you support your work):
Your software is running just fine on some desktop machine, server or maybe even on a embedded device. Then, product manager comes to you (due to a malfunction or maybe just integration question), and start asking you a few questions about the software you once knew, but the details faded away some time ago. One way to refresh your memory is to check the documentation, but…oops, cleaning lady threw away your papers…a year ago 
The other (harder) way is to go through source code. Not a very good option.
So, to avoid this scenario, I’m going to show how to create simple software project documentation. There are many commercial and free charting software on the market. One of the best I had the pleasure to work with is Microsoft’s Visio, but since its license is too expensive for my needs, and it doesn’t run on Linux natively, I use Dia, which is licensed under GPL licence.
Dia is a Gtk+ application, which runs on many different operating systems, from Windows, Linux, to different BSD derivates. But how to install Dia? On Windows, you download the binary package from Dia for Windows page, run the installer, and then the application launcher. On Ubuntu (or any other Debian derivates) open the terminal and write sudo apt-get install dia, confirm your selection, and launch the application from a Gnome terminal (Applications -> Graphics -> Dia Diagram Editor).
There is a difference in user interface between Windows and Linux. Windows version of Dia comes in a single window, while under Linux, document and the toolbar opens in separate windows. This is the “feature” I had the most problem with. When I open more documents, there are more toolbars, and then, when I switch between the documents, I never know which toolbar belongs to which document.
Dia for Windows
Dia for Linux
I believe people learn most, if they do an example, so let’s “design” a simple TCP client which has to loop through vector of IP addresses. In one loop it has to (try to) connect to an IP address, send it a “ping?” message, wait for a “pong!” message, and close the connection.
USE CASE DIAGRAM
I usually start with a use case scenario:
Use case describe the interaction between one or more actors (devices on those IP addresses we connect to) and the system (oursoftware). So, we need two actor icons (I use actor icons for both sides) and a use case balloon for each use case.
Simple use case diagram
As seen from the picture, use case only roughly describes the interaction between the two objects. It doesn’t even name actor more precisely, but just the “device”. Four use cases can be seen in a for use case balloons connecting the two actor icons.
FLOW CHART
We will create a more precise description of a system operation using a flow chart. Clasic flow chart is constructed between start and stop blocks, and it contains Activity and Decision/Branch blocks, and of course, the lines which connect the blocks. First, lets place a start block – this is the point where the application starts. Then, the application has to execute in the following order:
- Assign iterator to a beginning of a vector
- Is the iterator at the end? End the program if yes
- Get the item from a vector
- Try to connect to a client (timeout after 5 seconds)
- Success connecting to a device? Move to a next item if no
- Send “ping?” string to a device
- Receive data for five seconds, or until “pong!” is received
- Close the connection.
- Move iterator to a next item in the vector
Basic flow chart
This is the bare minimum of documentation which should be prepared before the actual development. This documentation will of course be altered during the development process, and even after the finish of the project (changes, bugs,…), but at least you will have something to look at when people will ask you really deep questions regarding the process of operation of your software, or when some weird bug occurs.
Both use case and the flow chart were not created by the book, they were created as I learned in high school, college, and in years of experience. If you need more information regarding the official creation of these kind of documents, search for UML standard in your favourite search engine, or on Wikipedia.
Another type of diagram I like to use is a state diagram, but I do this one when I create special type of software, which contains a State Machine.
