The Importance of Planning, Part 1: Document All The Things & Don't Skip the Scary Stuff

You are given a task "Sounds simple" you think. Time to get started, right? Finish the initial logic, and worry about the later details…later?

Or maybe it's one sprint's worth of work in a larger effort, and all that you need to do is clear, except for one part of it towards the end. But once you have momentum, it will be fine?

Or maybe you totally get the plan in your head for how the next 3 days of coding will unfold. It all made sense in the shower this morning or while trying to fall asleep last night. It is so clear even, that it seem like a total waste of time to write down the steps of what you will be doing, since it is so obvious.

NO. STOP. DON'T DO THIS!

To maximize your efficiency, predictability, consistency and reliability when working on project, please do not write code until you:

1. Know exactly what you need to deliver
2. Are confident that your understanding of this is equivalent to that of your client
3. Have written down the steps that you need to take to achieve this result

If it isn't written down, it didn't happen

An important rule for all of the following is that if something is not written down, then it doesn't really exist. Instructions, definitions, or plans that only exist within one's mental space or that are based on a conversation or chat are just not reliable. Memory degrades, recollections can easily differ (often undetected until the end of a project your client turns to you with a confused look after the demo), complexity can easily be missed, skipped, or lost.

And Slack or Discord is almost as bad: it is written, but it is also organized as a conversation which makes it harder to organize and use it as a reference, and is almost impossible to keep it up to date. Chat is great in the moment, but to me, in the long term, it is a medium where historical knowledge goes to die. Email is slightly better than Slack, but still not great (since you cant update it or give feedback easily).

In the ideal situation, definitions and requirements will be written down unambiguously in a tool or document that can be discovered, reviewed, annotated, and edited. Any medium where access cannot be given equally, where the content cannot be easily found by the relevant folks, where feedback cannot be easily given and acted on, and where the content cannot be update is going to impose a large hurdle in the way of achieving success in your initiative. Without this, anything defined can easily become stagnant, or without a feedback and edit mechanism might never achieve full accuracy.

These are table stakes: write it down!

Know what you need to deliver

In order to work on something effectively, there needs to be a definition of what the end result of the work should be. This is important, so going to repeat it:

In order to work on something effectively, there needs to be a definition of what the end result of the work should be.

This could be called the functional requirements or a Definition of Done (or maybe something else, depending on which system you use). Even for initiatives that are more discovery-oriented: without a defined goal, you will not meet expectations (other than by random luck).

This should be self-evident, but it can be surprisingly easy to violate this directive. Some examples:

1. After a conversation in an elevator where a stakeholder gives you a pitch on an addition to make a product, you go back to your desk and start adding it.
2. You finish a meeting where you had a productive session covering the whiteboard with lists and flow charts. You leave pumped up for implementing the items discussed and get right to work.
3. (The most mundane and maybe the most common occurrence:) Your PM send assigns you a Jira ticket with a very minimal description, and you begin to work on it without asking questions.

In any of these cases, you are starting to work before you have a clear, written, accessible definition of what needs to be done. And how can you possibly know that you are going to deliver what is needed when you can't even define what you think you are being asked to deliver?

(I would be remiss if I did not express thanks here to Joel Spolsky for his classic articles on Painless Functional Specification, Part 1: Why Bother, and Part 2: What's a Spec? These influenced me tremendously in this area when I read them for the first time about twenty years ago, and they are still tremendously relevant.)

Align on the vision & don't forget about the details

Now that you think you know what you are going to be working on, it really behooves you to ensure that your understanding about expectations is the same as your client (and there is always a client, even if it is your boss, your PM, a close relative, or an internal team). Even though (hopefully) at this point the requirements are written down, trust me: it is quite easy for different people to read the same thing and come away with different ideas. This is illustrated in the classic "Tree Swing" cartoon (origin unclear):

The more details that are missing, the more open to interpretation things are, and the bigger chance of a large variance between the functional needs as interpreted by different parties. This is why it is so important for functional specs to be out in the open and accessible, and for them to go much deeper than a high-level overview.

This is the part of the process where you need to get beyond the general big picture. Delve into the details. All of them. Including the icky edge cases, and the annoying complicated sections that everyone wants to silently agree to not talk about until later.

Often the most important or difficult parts of the project to achieve are the things that you gloss over on the initial whiteboard and don't have time for in the elevator pitch. Wherever the document of record is for the project/requirements: if you see something that you don't get, something that confuses you, something that feels off, something where there is a lack of "synergy" or "alignment" between your understanding and that of the stakeholder - ask the question. And don't move forward until you get an answer.

(Excess) size doesn't matter

I personally hate writing documentation. I am a master procrastinator. But I hate even more having to come back and redo work, miss a deadline, or deliver functionality that is different than the client's expectation. And I especially hate it when those things happen because I didn't take the time to think verify ahead of time that I know that I am working on, that the solution will fix the problem, and that I have things planned out.

But if you can do that, then by all means, do it in the easiest way possible, investing the minimal amount of time. I am not a fan of huge requirement template, of filling out sections of boilerplate that don't add value (and may actually make things harder to grok overall and are thus a net-minus).

Find a minimal format that works for you. Don't write more than you need to. Again, for something really simple, the functional spec could be 2 bullet points on the Jira card. Formality and boilerplate doesn't win you points (at least not ones that matter). It is much better to find a format and method that works for you and doesn't impose pain, mental anguish, or avoidable procrastination, rather than adhering to a larger format that is imposed on you (and that will invariably be harder for other people to read as well).

Break it down for me

Now that you know what you need to deliver and you have clarified any open questions, one more thing remains before you begin work: think about how you are going to accomplish this in detail, without skipping anything, and document it in a discoverable place before you begin working. You can then use knowledge of your technical plan to help perfect your approach for the entire task, have a good way to solicit feedback from others, and have a good artifact to leave behind after you are done.

There is more to it than that. Next comes breaking down the requirements into smaller pieces to develop a working plan. For that, proceed to The Importance of Planning, Part 2: Break it all down.

Every little bit counts

I know that this can seem intimidating and overwhelming. But please know: every little bit of improvement to a process (be it a professional one or a personal one) counts. Always leave things better than when you found them! If the best you can do right now is a private Word or Google Doc that contains a short description of functionality and a bullet list breakdown - you have already taken a big step! Keep thinking about the advantages of knowing clearly (with confidence) what you need to do before you begin work, and empower yourself to incorporate this into your repertoire of tools.

And please share your struggles, tips, and success stories as well.