Information technology is a means to automate, streamline and ease systems. However before we set out to build systems, we need to know why we are building it and what we will be building. There is no way to know this unless we take the effort to first gather a system’s requirements. We need to talk to various people who have a stake in the soon to be built system. The meetings are often voice conversations and it becomes really important to record what was spoken so that there is a permanent reference. In this article, I explain a two-phase documentation system to thoroughly record a system’s requirements using UML diagrams, storyboarding and timelines. Also please note that though this documentation system had its origins in Information Technology and Software Engineering, UMLs can be used to document the requirements for any kind of solution building.
Phase 1: Users and their use cases
The very first component of a system that needs to be identified is who will use it. There may be multiple types of users for a system. They are also called stake-holders. Users may be human users, other systems or something automatic / machine-induced such as a timer which goes through your system at a certain time of the day, a web crawler, etc. Every user has a point-of-view of the system in terms of what he/she/it wants to achieve. Identifying the key users is the very first step to building a system. Please note that this, as well as all other steps CAN be done later while the system is getting built or after some iterations of the system has been built. UML is happy to encourage incremental (AGILE) development as against a waterfall model. If you see that more types of users can benefit from the system, they and their use cases can be added later.
Let us consider the example of a solar panel charger system. As mentioned in the intro, UMLs can be used to model any kind of system, including non-IT ones. The following users can be said to interact with the system.
- Service personnel
Users play different types of roles in a system. Each story is called a use case. While drawing a use case diagram, an exhaustive list of all the roles that a user can play in the system is prepared and represented in a diagram.
Considering our solar charger system example, let us consider the consumer. The consumer will have the following roles.
- Charge the system: Expose the panel in the system to sunlight for charging.
- Use residual charge in the system: Connect an electronic device to the battery in the system for usage.
Phase 2: System flow
After all the users’ use cases have been identified, it is time to document each use case exhaustively. The flow of each use case is documented in as much detail as possible. Along with the normal and successful flows, failed flows are also included. Every detail about the inputs to a flow and the outputs that the flow generates are recorded.
Let us look at the ‘Charge the solar panel’ use case as an example of how to make a use case flow.
- The consumer places the solar panel of the system such that it is exposed to sunlight.
- The solar panel attempts to draw the incident sunlight and convert it into potential difference.
- The potential difference passes through a controller circuit. If there is sufficient potential difference, a yellow light is shown to the consumer indicating that the system has started charging.
- Failure 1: If there is not enough sunlight available, a red light is shown to the consumer.
- The potential difference is applied to a connected battery, which starts charging.
- Once the battery reaches 100% charge, the system turns off the yellow light and shows a green light.
- The consumer may stop the exposure to sunlight, if he wants to.
As we can see, the steps have been outlined in fairly good detail as a requirement. The failure case, where there is not enough sunlight has been taken care of. Let us now see the sequence diagram for the above description.
The two phase system described above is absolutely vital before we can proceed to design a system. Is your system requirements gathering team using the above two phase design with the UML diagrams to document requirements systematically. Do you use UMLs in your process? Are there any other phases / steps that you use to document requirements in even more detail? Please let me know in the comments below.