Thursday, March 28, 2013

Writing Documentations - Walk in when everyone walks out

In one of the projects that I have worked in, the list of the document requirements were quite long and *un*fortunately I was assigned to do them. On one hand it was boring and tedious, and it doesn't boost my morale when I am almost sure that no one will be reading them. On the other hand, this was a golden opportunity for me to disect a project and analyse it inside out. Here is the document list that was passed down to me and expect a list of filenames (with content of course) in return:
  • Software Architecture Document (SAD)
  • Functional Specification
  • Technical Specification
  • Reusability Analysis (of some of the components from previous projects)
  • Test Procedure
  • Test Cases
  • User Manual
It was a long list and I didn't know where to begin. In theory this is a list that needs to be completed by several people, but because the project was shorthanded I volunteered to complete as many and as much as possible to save some time for the others. As I have only written some of the documents above only once in my entire life, I am not about to start teach you how those are written and every company have their own guidelines regarding them. I will just tell you the benefits by actually take some time and complete them in a detail manner. In the next post I will mention of how these documents can give you a better idea of what you do affects the whole picture. In conclusion, documentations are important for leaving behind information for the others but at the same time by writing them it will also challenge you to think throroughly of the design and if it in fact is done correctly and serve the true purpose. So don't run away from the task, instead walk in when everyone walks out.

Thursday, March 14, 2013

Documentations - The priceless element in a software project

Documentations, when you have it you don't see the value of it (Price-less), when you don't have it you would be giving anything for it (Priceless).

This is especially true for companies who not just develop the software for their customer, but would also be responsible for maintenance as well. Everything seems to be working fine at delivery, acceptance tests passed, acceptance letters signed and the final payment received. At that moment, no one pays attention to the documentations that come with the delivery. Someone may even be agonized over the wasted hours on them.

Fast forward to 2 years later, the customer wants to add a couple of new features. The lead architect along with a couple of developers have since delivery resigned. No big deal right? They are programmers and can find their way around the code if enough time were given. Well, as soon as the solutions opened in Visual Studio, tears/sweat starts dropping down their cheeks as if they have just opened Pandora's box. There are hundreds of files that hang together in a manner that cannot be understood. To make the matter worse, there aren't even any comments written by the code.

This is probably a scenario we have came across at some point in our career. So why do we continue to ignore the importance of having documentations to go along with a software project and fail to dedicate enough resources to get it done in a comprehensive manner? A common answer I have heard was that the documentations were never read. So because the documentations were believed to be useless, we stop writing them and so the negative spiral goes on.

So for all of you who are designing a solution or doing implementations at the moment. Please take a few moments to document what you are doing. A few moment spent by you today will save a lot of moments for others in the future.

This post will follow by another on what kind of documentations are crucial in a software project and some of the key elements that should be included. Stay tuned.