subject: Good Software Documentation [print this page] Good Software Documentation Good Software Documentation
Software Documentation may vary from project to project depending on the complexity of the System to be developed. Documentation level is also dependent on the company strength and standard. For some companies it is for only compliance purpose, again for some it is both compliance and a need to track maintenance and keep history for the existing and coming projects. Whatever the company standard is, documentation is a need for effective development. It is a common scenario for software companies and for other companies who develop software in house that the turnover rate is very high. So the situation comes that people who designed and developed the software is not in the company anymore. Then the company faces a big problem in adapting a new software engineer with the System. In such a case, documentation plays a big role. In the software development life cycle, there are many areas to document which can help to simplify the process. In this article, I will focus how documentation helps a newly joined software engineer in a development team.
I will focus on the documentation level of a CMMI Level 3 accredited company who develop application software in Bangladesh. I am focusing on the areas of documentation that is visible to a software engineer in the process and how the documentation is important. I will miss some areas of documentation which was not effective for a role of a software engineer to work in the construction phase.
A software company has an organ gram and role is set according to the post the person holds. In the tree, the bottom layer is software engineers, a layer above is the senior software engineers, the above layer is business analyst, then the higher is Project manager and the boss of a project manager is the software architect. A team with this hierarchy is responsible for the full lifecycle of a software system.
The software engineer is appointed in his job for some responsibilities set by the company. Generally a software engineer is appointed for the construction and deployment phase. When a software engineer is in the construction phase he has to go through some documentation both some created by him and some created by his superiors. You should imagine that the documentation must be in a structured format, so that the new software engineer who has joined the team recently can operate his role very efficiently.
At the time of work, the software engineer has to understand the "what" of the proposed system. So his superior in the role of business analyst and project manager must make a document of requirements and forward it to the young software engineer. This document is called the Software Requirement Specification (SRS). This document should be self describing. The SE will need to understand the users and their interactions with the system. So in this document, there should be a brief description about the Use Cases of the System. The functional requirements must be clearly defined in the SRS. The business rules and the constraints should be defined. The document should describe the data models and data dictionary. The Software architect will divide the whole System into some modules and break a module in some units. The software engineer will focus on the documents of a particular unit. The software architect will design the database and create a document describing his database design. The project manager along with the software architect will design prototypes of an individual unit. All these information will make a software engineer to start his thinking to implement the software coding. Now at this point the software engineer will need a blue print of the architectural design pattern of the software solution. This document will be provided by the senior software engineer to the SE. This document is called the high level design (HLD). In this document, SE will find the project structure, the logical layers, and data models. Senior SE will give a document of all classes, interfaces, model classes and coding convention for the specific units. The documents of the Senior SE will make the SE to start coding. Now starts the role of a software engineer. The SE will conduct Component level design and create a document of Low Level Design (LLD). While doing the LLD the SE will do an extensive level of thinking for coding. The LLD is the document of the code. If the code changes at any time, the LLD will have to be changed. The advantage of doing LLD is that the thinking is finished and at the time of coding, only typing will be done. But in practice, CHALLANGE comes at the time of coding. But there is a senior SE who will solve the challenge along with the SE and Team leader. In LLD, Test Cases of the code have to be documented. After coding the SE job is to do Unit Test, testing the smallest unit of the codes that he has developed. He has to document the results of the Unit Test. Then the solution goes to the QC department for quality check and there is other further documentation needed.
This is how; documentation makes a Software Engineer (Developer) familiar with performing his responsibility efficiently. Even when a new SE will work on the existing System he will be benefited by the documentation that the SE developed. We know that we can develop SW without documentation but there are many flaws in the practical environment if we make no documents. The flaw may not be visible earlier but will come in the long run.
