Friggin Charts…

Posted by Jonathan Ng | Filed under Technical

Without a doubt, program documentation is vital in every software/application/script that one develops. It’s importance increases when the size of the project increases. Data Flow Diagrams (DFD), structure charts, entity relationship diagrams etc, there’s just so many different ways of documenting your codes. So many that I begin to wonder the purpose of them.

In my “mini-project” that we’re given in college, we’re required to produce all of the above mentioned diagrams/charts. Worse of all, these diagrams must adhere to strict standards, that God knows who set in the first place. Making your documentation standardized is surely important, but to what extent? There were many cases, where me and my friends were cosidering the level of detail that the diagrams (esp. DFD)need to cover. In fact, we feel that we waste a lot of time, drawing these diagrams, making sure they adhere to the “standard”. Aren’t the purpose of these diagrams to make understanding of the application easier? Why waste hours on it?

I simply feel that as long as the diagrams make sense, and is understandable, then it’s fine. Why waste time thinking about how detailed the chart should be? In our DFDs, “validate user data” is a “process” that must be included. Common sense tells you that you need to do validation no matter what. Why waste time illustrating things that you already know?

The problem with DFD is that it only gives you a rough idea of where the data would flow. Most of the time, you’d easily figure that out with a quick look at the program codes. However, what DFDs don’t usually cover is how your program codes work. They do not illustrate your approach at processing the data. So basically, DFDs are as good as useless when it comes to helping someone else understand your codes.

Until now, I’ve yet to learn about souce code documentation, which I feel is so much more important. Perhaps this is also due to the reason that I’m only active in web-development, where projects are so small that inline comments are good enough.

What kind of documentation do you do?

Permalink | March 21st, 2006

One Response to “Friggin Charts…”

  1. Ben Says:
    March 23rd, 2006 at 12:29 am

    Diagrams, as part of documentation, are very important. This is especially so when the project is large, and involves a few developers. The diagrams/documentation serve to communicate a common understanding among developers working on the project.

    Even assuming the number of developers is very few, in future, you may not remember what your modules perform. Also, consider the situation where the development takes considerable time to complete, and new developers may replace exsiting ones. This makes clear documentation even more important. No assumptions should be made, everything has to be documented properly and clearly in a way that everyone understands (i.e. adhering to standards).

    In this respect, documentation serves as part of an organization’s knowledge management process. If there is no documentation, the organization will suffer from “organizational forgetting”, i.e. stock knowledge is lost, when developers leave the organization. And it will depend on the existing developers to “impart” this knowledge to the new developers, something unlikely to happen. Loss of this knowledge is going to be costly as time and effort previously invested is lost.

    In larger organizations, documentation is also used by auditors. Auditors will check that the applications are working as what is documented. Deviations from the documented specifications/functionalities will be alerted. Lack of documentation will become a problem if an audit is to be performed.

Leave a Reply