Why software documentation is important?

Everytime I got a new project from new or existing client, for the last 5 years, what I did was, straight away to write the software, design the database, test, deploy and for the next few months, do some tweaking, and more debug, and more adjustment and getting new requirements and write the new functions and later more bug and debugging and later not able to claim the payment. There is no clear cut to put where the software development and the deliverible should stop.

There is one project, Im working on at this moment, already 2 years, since November 2016, not able to claim the payment since the end user keep asking new function and new features. Why I did not stop to entertain this client? Because of my very own mistake. I DID NOT DO ANY DOCUMENTATION!

I did not put a record what is the deliverible on phase one, phase two and where and when I should claim the payment. This has been going on since 5 years ago and the project that I invovle two years ago, really knock me hard, direct on my head! What I wrote in the quotation was : Electronic Purchase Order System. When they ask for more features in the system, I told them, ‘No, this was not in the early discussion’ . But they replied: This should be in the system!. I just comply because I know, this was my big major mistake, of not create any documentation to write down what should be in the system.

For this people, its like buying a car. When they feel like, the should be reverse cam in the car, they just request and expect me to install the reverse cam even the reverse cam was not mention in early discussion. But they told me, this is part of the car. Your quotation is a car. Then Im trapped! Why should I just abandon the project on move to another project? I have this feeling, — if I deliver and service this company, I will get another project with them. Which is very true, I got another project with them. This time around, I started with a system flow chart and together with the features. This time, I charged them more, to cover up my lost in the previous project.

If you understand system analysis and design, they are four basic phases – Planning, Analysis, Design and Implementation. Looking at the flow, 3 out of 4 involve documentation and not yet on the coding or writing the software. On the next project, which is very, very huge project with one establish University, we are going to do documentation first.

With lesson learnt from previous project, that does not have any documentation, starts from November 2018, all project will need documentation. We need to spend time doing the documentation, even the excitement of doing documentation is not as good as doing the coding, but we need to put this way : You want to spend more time debugging, or less time debugging with few time spent on the documentation and record?

What documentation need to be done?

  1. Requirement gathering minutes
  2. Features listing – from requirement gathering. This include all create, read, update, delete and other functionality
  3. System flow chart
  4. Proposal
  5. Software Agreement
  6. Graphical User Interface – GUI design
  7. Database design – internal use
  8. Flow chart for sub – system – internal use
  9. Timeline planning – gantt chart with milestone
  10. Costing – Price quotation
  11. User Acceptance Test – UAT. This generate from feature lsing
  12. Deployment

To craete the documentation, is the REAL job of software engineer. This is what really software engineer does. The one who writing the codes, is actually, software programmer. Put it in this way. If you are building a house, the one who laying the brick to create the wall is similiar to software programmer. He just lay the bricks, make sure the wall in straight line and all the measurements are correct. He no need to think that later this wall need to be a hole to do wiring.

Diffrent with software engineer. If a software engineer going to build a house, this guy need to think, how big is the house, where to put the light, why the aircond need to put at this exact wall, not at another wall. Why the window need to face north, not south? Why the power supply need to be this much of power? All this thinking question and answer, need to be documented out. This is really what a software engineer does. The next step of software engineer career is system/software analyst and later, system/software architect.

But before became software engineer, they need to understand on how to do codes. They need to lay bricks, to build the wall in the house, before able to plan the whole city! Intresting job, huh?

— adam —


Software engineer by passion

Leave a Reply

Your email address will not be published. Required fields are marked *