7 benefits of blueprints in software development

In this series of articles, I want to share exciting things about our way of working: challenges, organisational methods, work techniques, technical solutions, and much more. Enjoy!

Time is in scarce supply in the software development business, and at least 25% of programmers work overtime several times a week. And in many companies, crunch culture is a well-documented malaise.

As a result, many developers have the instinct to start coding asap, like racing horses with blinkers on. The first casualty of this approach is design sketching.

Time pressure is not the only factor, though. In some instances, coders ignore the design aspect because they either underestimate the value of a sketch to the project or are too impatient to bother about it.

We think they are making a huge mistake. Here is why:

Software Development is Like Construction

It is easy to draw parallels between software development and property real estate development. In the latter, every project begins with a sketch by an architect or design team, and this is followed by detailed plans that get passed on to the builders.

Granted, we don’t have quite the same division of labor arrangement in software development. But the apps and software we create are no less complex than a building, and faulty designs can lead to catastrophe in both instances.

That’s why large and complex projects (like an entire Operating System, for instance) usually have Software Architects designing the initial macro vision or blueprint of the system.

We believe this practice can deliver tangible benefits even in smaller coding projects.

Architect or Archaeologist?

Early design sketches can make the difference between a software architect and a software archaeologist.

Think about it – how do archaeologists work? They start digging from a visible spot of below-ground remains and continue to discover piece by piece hoping for a structure to emerge from the earth. Coding without a blueprint can end up like that.

The result is almost invariably messy. With an architectural approach, you would not start writing code without having a sketch or tech spec to provide a roadmap.

This way, you and your team know exactly where each piece of code needs to end up. The result is code that looks well-built, with everything neatly in place.

7 benefits of writing Tech Specs

Keep Your Focus

It is easy to get your mind wrapped up in the code – often, you may overlook certain key aspects, which can open up pandora's box of logic errors, bugs, and hidden vulnerabilities.

Sure, bugs are always a part of the coding journey. But you can still mitigate them quite a lot with a plan or design sketch.

Improve Decision Making

Coding is not a linear journey. As you get deeper into a project, you may need to shift or pivot for better results. Lack of a plan increases the risk of wrong decisions at these junctures.

With a proper blueprint, you will first try to map the potential crossroads you may encounter in the future and map out the different options. It will improve your ability to make the right decisions in high-pressure situations.

Save Time – Lots of It

Without a design, you will waste more time refactoring, debugging, reworking, and testing the code. Do you know what costs way less time? Facing the same errors during the design phase.

Reduce Technical Debt

At the code review stage, you must prioritize which fires you want to put out. If some errors/flaws don’t look critical, you may end up leaving them untouched. Over time, this makes your code progressively messier, even unfixable in some instances.

Early planning and blueprints can mitigate this code debt if not outright avoided.

Facilitate Collaboration

A blueprint makes it easier to share your ideas with a team. Validating your idea with the help of other programmers is vital in coding – inputs and different perspectives can help improve your approach or give you new ideas for better solutions.

Improved Planning

Sketches and blueprints make it easier to prepare reliable estimates of a project timeline and the effort you need to put in. With coherent and realistic milestones, you can monitor progress more efficiently and improve your chances of a successful implementation.

Build software design skills

The system encourages engineers to develop the habit of foreseeing a project, which is vital if you want to be a better developer. Plus, you also get additional training in architecture and system design skills, which will only help you in your software design career.

This is How We Do It at Getik

Our System

The Blueprint step is fully integrated into our development process as a Jira sub-task for every story. This ensures compliance across the entire dev team and prevents engineers from skipping it. Each blueprint is reviewed by at least one other developer before the coding process begins.

The structure of the Blueprint covers important areas of a project:

  • Technical spec: a translation of business requirements with the highlight on data flows
  • DB tables and packages involved: a description of the impact on existing objects or the new ones to be created
  • Internal API (Backend-Frontend): JSON structure of each request/response
  • External APIs if the case
  • Testing scenarios: the list of important flows to be covered by the QA squad
  • Design: UX squad produces the screens and adds them to the blueprint after validating with the Product Owner

This structure makes the actual coding a relatively straightforward process, with fewer unpleasant surprises along the way. Onboarding members from a different team becomes a cakewalk. They don’t have to spend too much time studying the module. With the help of a blueprint created by senior members, even rookie engineers can jump in and start coding.

We use Markdown, which allows us to store ASCII files on the GIT repository for easy track changes. This makes teamwork and coordination easier than ever before.

Finally, we do not rehash existing blueprints for new requirements. Brand new blueprints are drawn from scratch to ensure that they fully reflect the tasks or objectives added to the projects. This way, we can track the new features and changes easily.

Final Thoughts – Don’t Stop Documenting!

Creating an early plan or blueprint is vital in the early pre-coding stages of a project. However, you should not stop writing there. Here is why in one simple sentence:

The code does not tell the whole story.

Why did the dev team make a key decision at a particular point? Why did they pick one feature and dump another in a later version? You cannot find answers to such questions in the code.

If there is a change of guard and a new team is shipped into work on a long-standing project, this can lead to severe disruption. To solve this, the blueprints should contain the following information:

  • Each decision in the coding process
  • The rationale behind each decision
  • All alternatives that were considered

At Getik, we are constantly looking at ways to improve our blueprint process. Our future improvements to the process will try to focus on documenting the choices instead of just looking at the implementation. This way, the blueprint will retain its value across the entire software development cycle and maybe even beyond it.

Growth
Ghenadie Dumanov
September 9, 2022