Coding is often triggered by impulses, someone asks for a new feature and soon we go and start coding it with only a brief expected result in our head. From experience I can see that this can never be the ideal situation, sometimes it works but when something goes wrong the time spent on analysis is too much – and sometimes the incidents are corrected with workarounds rather than correcting the core of the new functionality.
I focus on the negative cases because when everything works as expected no one complains about the lack of design, but everything changes when there is something that is not working as originally intended in the head of the person who asked for the new functionality.
The use of frameworks reduces the risk since many of the processes are already defined, but each programmer has his own way of implementing it, which can also influence the approach to problem-solving.
Most people who ask for new requirements expect us to have their business process in our heads just as visible as in their heads. They hope that by giving only the main details, the requirement can be fully identified. With the experience of other developments, programmers can sometimes identify requirements not raised by the requester, but the best practices say that everything should be discussed within the team – since only by doing this the best solution can be implemented. And how I love a good discussion 🙂
Below are some of my tips for good software design:
- Pen and Paper discussion
- While discussing with the team, make sure you design the frontend of the software so everyone is aligned with what goes in your head; Visibility of your design process will provoke discussion about other requirements;
- Speak with people from different hierarchy levels, don’t forget that sometimes the managers don’t know the full details of the day-to-day work. A good manager will ask the collaborator to be present in the meeting;
- If you don’t want to kill trees the ReMarkable is a very good option, I use it every day.
- Design the relationship in a diagram
- A diagram of the full process gives visibility of who are the intervenients in the new requirement. Sometimes a new requirement for a financial requirement will impact and have as the source of data the operations department;
- Additionally, a diagram where we can see all the other customisations and dependencies of the standard functionalities will give the visibility of other things that can impact the design of this new feature;
- Make use of colours for the diagram boxes, i.e. green for standard modules, blue for customisations, yellow for integration processes, pink for reporting… I think you are getting the idea 🙂
- One awesome open-source tool that I use every day too is the web application draw.io – They love diagrams and me too.
- Mockup the software
- Create a simple mockup of the feature without implementing the business logic. This will make visible how the UX interaction will be made and also will show some progress with the idea;
- Several mockup tools are available, normally I like to use the framework where I’m working – just because gives you the same look and feel of the final solution. Another option is to use draw.io to mockup it.
- Meeting to validate the process diagram and the mockup
- This is a step you can’t miss because you need to make sure you show the final solution, this will help the team to get tasks planned and organised so they can test and do user acceptance test;
- This will also evidentiate everything that is out of scope;
- Write-up of the requirements
- As soon everything is validated you will need to document everything.
- Based on my experience I like to start the documentation from the initial step and revisit it in every single step. The big benefit of doing this is the teamwork you can get helping you defining the business logic from the beginning as this will trigger discussions and questions that require an answer from the other intervenients;
And that’s all, it’s not difficult.