Tinkerer

Adventures in code RSS Icon


You Aren't Going To Need It - Yet

You’re on a project. You’re developing an API to count the amount of apples in a cart. You expect to have it done, and people using it in 6 months.
Obviously this API needs to be documented, after all you don’t want your consumers to have to guess how it works.
You all agree, that when writing a new endpoint you’ll document it properly.
Four months later it’s looking good - you have a bunch of endpoints that are beautifully documented.

Oops, turns out someone had misunderstood something. You actually need to count occurrences of different fruits from the cart. And there’s multiple carts.
Well, that’s life. We’re agile. Requirements change.
So now it’s time to create some new endpoints. And document them. All over again.


In hindsight, the right call here would be to write the documentation at the end, when the API had stabilized. Could we have known this in advance?

When deciding when to perform tasks, there’s a few things we might want to take into consideration:

The Right Task For The Wrong Time

Let’s look at a real-life example where I wasted quite a bit of time, doing a task at the wrong time.

I used to work at a project with reasonably complex cloud infrastructure.

At the start of the project, I spent a week or two writing scripts to automatically create the whole cloud environment.
Six months later as the project evolved, many of the cloud components changed.

Every time a cloud component changed, I had to change the scripts. Doing that could easily take a few hours, and at this point in time, we didn’t really use them very much.

Let’s try to use the questions to see whether or not we could’ve been smarter:

In this case, we should have realized that the value gain wasn’t worth the cost. Particularly not when we were this early in the project. The right call would have been to build the scripts, when provisioning environments by hand happened so often, it became a major pain point. This might never have happened, and we never would have written the scripts. We would have maximized the amount of work not done.

So next time you’re about to start a large task, ask yourself “Is this the right time to do this?” - just maybe it’ll save you from doing it multiple times.

  1. Unless you push everything to the end - in which case you’re not very good at project management. 

  2. Value here, can also be that you learn something from it. So if you learn something about how the API should work, by writing the documentation, it might create value. 

  3. Even though we thought we were pretty sure, of course. 

Did you enjoy this post? Please share it!