Want Better Software? Write Less, Talk More, and Let Engineers Do Their Job

The keystone of product development is the right and understandable goal. Every feature or product change has to respond to global product strategy and have a positive impact on business. Otherwise, why are we ever doing something?

Business goals may be represented in different ways but the most common approach to achieve them is product requirements that express countable and finished results in every piece of software. In this article, I define requirements as a complex of text and graphic (schemes, mockups) specifications that describe solutions for business tasks, that are usually processed by engineers during product development.

Depending on the methodology used and the current stage of the product lifecycle deepness of requirements may vary. In some projects, time-to-market criteria and fast hypothesis checks are the most valuable part of the process. On the other hand, you may develop custom software for a big corporation or even government structure, when you have to gather and organise a backlog of consistent requirements to finish the development project on time, with minimal costs and compliance with original, sometimes unclear, expectations. Or you may work in a product company that develops their own software and you have to carefully evolve product features without breaking changes that may negatively affect current capabilities and market position.

Requirements can take different shapes in every scenario. But in any of them highly valuable a figure of a product specialist, who can figure out the best and sufficient volume of documentation to reach company and product goals.

Why do we ever have to prepare the requirements?

It is not an obligation. But in project and product management you have to mitigate risks. You could release even the complicated ERP system, spending whole days in meetings, reimplementing features in real-time, and facing myriad problems and product bugs. Team members will be burning out and the project may stuck in production hell. Nevertheless, with enough persistence you may receive a product of sufficient qualities. That’s a piece of humour and I hope nowadays never ever somebody will try to release an ERP system that way but we are talking about extreme examples.

On the contrary, the existence of developed requirements that can establish goals and attainability of project, functionality or improvement helps a lot with planning and prognosis. Mistakes in requirements are the most expensive ones in development because it takes the resources of the whole team to fix them. Therefore it’s better to dive deeply into a domain, provide interviews with every stakeholder and specify every detail to avoid risks at all. Calm and composed you can develop software based on well-written documentation.

There is also a downside. Willing to avoid and protect yourself from risks it’s possible to overcomplicate the development process and establish a process of designing highly detailed requirements. This process is expensive, takes a lot of resources, especially time, and may contradict modern development approaches, that recommend work iteratively with fast result checks.

A natural question follows how to find a balance between precise and detailed specifications that mitigate risks and being fast and agile.

The boundary of requirements

Any recommendations should be implemented according to the project context. Further down I would like to propose my view for B2B products development. The key idea may be described by the phrase: “Product specialists shall not impose a way of realisation to developers”.

The requirements should contain a sufficient amount of details on how to implement a piece of software and solve all necessary obstacles. Product specialist has a rich toolbox of instruments to make them clear: the goal may be established via a complex of process diagrams in different notations (BPMN, UML); every change could be covered by functional and non-functional specifications; the whole user case may be designed in clickable interface prototypes. Sometimes you could use everything at the same time. For other changes is fine to use only a few instruments.

Even so, the source of requirements should not affect and impose technical details of realisation instead of an engineer who knows better how and when to use different technologies.

Let’s make an example. We have to implement a new web form for some objects. During requirements design, we should cover the following topics:

• What kind of fields should be implemented on the form?
• Content type for every field (string, int, datetime).
• Range of values for every field.
• What kind of fields are required and non-required?
• How we validate every field. Where we could use only digits, where we should implement protection from the copy function. Or how we should process data in the field with an email address.
• How we should log user actions, do we have some behaviour analytics?
• How we will show error messages if something goes wrong? Do we have some dynamic updates?

This list of requirements should be sufficient to create a working and reliable web form by a qualified team of development engineers. Yet we avoid plenty of details:

• Should we use REST or GraphQL for implementation?
• In which tables in the database should we store the values?
• How the endpoints will be named and how we will document them?
• What kind of dependencies we should use for user interface and dynamic updates?

Years of management recommend avoiding fixation on technologies in product requirements. It doesn’t mean that the team should not discuss them. Quite the opposite, every team member should comprehend how every piece of software is working and what technology can be used for implementation. The grooming process is a great way to reveal and identify the best way of realisation. Also, exceptions are always possible. For example, if during the design of this web form, we would like to try to use GraphQL and test the hypothesis, it’s fine to explicitly include this technology in the requirements. But it’s better to mention it somewhere in the notes and additional info than in the main section of the specification.

When “Surface-level” requirements might actually help

Suggestions may be controversial, so it’s useful to provide a list of cases where this kind of software requirements works in your favour.

• Implementation should be determined by the most qualified specialists.

  As far as I see product development companies, in majority of product specialists don’t have huge experience in software engineering and don’t use and study technologies daily. And that's even great because that’s why we have different specialists in our teams.

  Depending on the domain product team may include a mix of business-oriented product managers and business analysts or more technology-engaged system analysts in different proportions. Nonetheless, the main purpose of these specialists is to gather and determine business needs rather than architect the whole solution. Imposing technical implementation by the product team without complete comprehension of the pros and cons of every technology may lead to suboptimal decisions. Some specifics of the software can be missed and lead to technical debt and future problems.

• You should leave some fun to engineers.

  Requirements with excess details are hard to understand. But also leads to a decrease in creativity and internal growth of the engineering team. Developers should find the best technical solution for every business need by themselves. Sets of requirements may be aggregated into brand-new universal services that will work fast, secure and reliable in the future. Engineers shall decide how the codebase should be operated. And that’s why in developed teams we have a position of software architect.

• Technologies change too fast.

  Products evolve during their lifecycle. Some dependencies or technologies may lose relevance and transit into the sunset phase. Maybe the whole tech stack could be changed because of the new cloud infrastructure. Or your team will find a new proprietary solution that makes development much easier. Various factors could cause this to happen but it mustn't lead to the necessity of rewriting the whole product requirements knowledge base. The absence of deep and technical details in product specifications helps to use the same requirements throughout any product stage without depending on the technology stack. I hope nobody will face the task of updating hundreds of articles. It’s expensive and time-consuming and it’s better to spend these resources for something more useful for the product.

When this approach doesn't work or even backfires

In some cases, these recommendations about requirements without excess technical detalisation might not be suitable and it’s better to avoid them.

• Using out-stuff or third-party development teams.

  Under those circumstances, it is highly important to keep technologies and dependencies under control.

  The in-house development team have internal rules and standards of implementation. Programming languages, frameworks and patterns of programming will be chosen depending on software history and strategy. The same with decisions about proprietary or open-source packages with suitable licence policies. The team have to calculate risks and recourses for maintenance according to the whole software life cycle.

  If the piece of software is developed by an outsourced team it’s necessary to document your vision and install boundaries, because consequences of made decisions may not be the problem of this team in the future, but it may be a problem of an in-house team. In this case, it’s better to prepare requirements as detailed as possible.

• The team is still building its technical skills.

  If the product team is more familiar with the software and the development team is brand new or the team is still growing in technical capability (for example there are a lot of Middle and Junior level engineers) it is better to formulate more detailed requirements and later simplify them according to the team evolving.

• Changes are too simple to describe at a high abstract level.

  For some tasks is harder to create high-level requirements because it’s easier to describe a task on an engineering level. Especially if the task is connected with technical debt or some low-level improvements.

• The software has to be “bulletproof”.

  If the software has to be a hundred per cent reliable and will not change in the nearest feature, it’s completely understandable to provide well-detailed and revised requirements.

The final decision is always up to the manager

Product management decisions have to be adopted and validated according to specific of every company and team. Risk protection costs a lot of money, but working without proper requirements may too. You have to assess the capability of your teams to establish the right process. It’s even fine to have different levels of requirements for different teams depending on software specifics. However, it’s necessary to have a whole toolbox of instruments and apply them meaningfully through the software lifecycle.