A spec(ification) is nothing more than a business or engineering requirement that software engineers use to implement features or solve bugs.

Is that so?

In our current software development process at Savi Solutions we get more than that. Because we're a startup is not a surprise when the business requirements are not clear or don't reflect what customers really want. That happens more often than we'd want to and is usually due to the lack of technical knowledge the customers have, which is expected.

The engineering requirements are not always clear as well. Usually, the person writing it has no domain knowledge of the project at hand or is not clear what the best solution is, which is part of our job as software engineers.

So, I've been observing for the past 1.5 years that a spec is not a dead document and is not something someone above you had determined what your next task is and you should blindly follow it.

The best engineers I work with always question requirements, context and needs and always think before starting writing actual code. And that's what makes them problem solvers and become the go-to people to ask challenging questions in the engineering team.

With that in mind, I started seeing the spec as a living document that's not just to be accountable for what I've been working on or to have a standup message ready to post every morning or a set of tasks written in stone.

I've found that the spec doc writing process can have many faces, like:

• a moment to plan ahead which specific tasks should be done and in which order (should update a schema before pushing the migration?);
• where you bring context to your mind by checking important files or functions that could be changed;
• a powerful way of documenting and tracking your ongoing work;
• notes from your present self (on Friday) for your future self (on Monday) so you can clear your head during the weekend and start the week knowing what should be done;
• a way of cleaning your head with the problem at hand so you can start thinking about other possible side-effects you should consider when implementing the feature;

As a result of those possibilities, a detailed spec document can take some amount of time to be done with the outcome of reducing implementation time, future bug correction and code review rounds. That not only improves our productivity as engineers but also improves the productivity of the entire engineering organization.

#software