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:

• Can the task be delayed?
  If we have someone who needs this done in six months, and it’ll take us six months to create, we obviously can’t delay it. In our example, the documentation probably wouldn’t take more than a few weeks at most - meaning that we could have delayed it until then.

• Does completing the task create value right away, or only in the future?
  Some tasks, like tests, create value the minute they’re created. Documentation for external consumers doesn’t. It only creates value when the external users start using the API.

• What is the price to maintain the task, when requirements change?
  I like to call this the upkeep. Different tasks have different upkeeps. The upkeep for maintaining API documentation for five endpoints is low. The upkeep for maintaining pages of tutorials, quickstart examples etc, is much higher. The higher the upkeep, the riskier it is to do too early.

• How uncertain are the requirements?
  Are we in a mature stable project, or in the wild west, in regards to requirements? The more mature and sure we are about the requirements, the less we need to be afraid of tasks with high upkeep.

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:

• Can the task be delayed?
  Yes. We did this because we figured it would pay off in the long run. We figured we would save time each time we had to provision a new environment.

• Does completing the task create value right away, or only in the future?
  It only creates value when we have to provision new environments, and as mentioned before - we rarely did that.

• What is the price to maintain the task when requirements change?
  It was very high. Provisioning scripts are impossible to test, and can take quite a while to run. Using a few hours every time a service changed was not unusual.

• How uncertain are the requirements?
  We made this decision in the start of the project, when we were very uncertain about the requirements and the cloud services we needed. If I’d been smarter, I would have realized that this meant I should have postponed this work.

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.