How much should you document your own tasks?

I had a wonderful question asked to me today from one of my engineer about how much information should be documented in a task assigned to yourself.

How much should you document your own tasks?
Photo by Glenn Carstens-Peters / Unsplash

I had a wonderful question asked to me from one of my engineer about how much information should be documented in a task assigned to yourself.

This is a very good question because it is undeniable that it's much more efficient to document well tasks assigned to others. However, if the task is for yourself, you are effectively generating information out of your head... to put it back in when its time to do the task???

My position on the value of tasks in general is pretty clear:

Tasks are your best friend πŸ‘Ί

However, on that particular topic it's not too clear what is the best course of action. On one side you ensure that you have all the information you need when it's time to do the tasks, but on the other hand time is wasted if the task is obvious.

In my opinion however, you should always tend to over-document even if the task is simple. Let me explain why!

It's not guaranteed that you will be doing the task

It will happens. You create this task with an 8 word title that will take you max 5 min to clear up and out of the blue you now need to focus on more critical stuff for two weeks.

When you come back someone has been stuck on your task for way longer than they should because they haven't properly understood the scope of it.

By setting clear requirements for what needs to happen with the task you ensure that you don't actually have to be pinged so that it gets done.

This is also another hidden benefit. You can technically create very well detailed tasks so that anyone from your team can clear them up while you are out fending off bigger problem! βš”οΈ πŸ‰

It helps you create the right mental model about the issue

Not documenting the task is a big disadvantage when the problems are difficult because all of the parameters kind of live in your head at all time.

This is bad because you are juggling with two very different things:

  • remembering the mapping of what you have to do.
  • figuring out how you have to do it.

By having tasks well documented and sub-segmented (i.e. this task include the following 12 mini-steps that I need to solve) you don't have to plan at the same time that you solve!

Taking a deep breath and crafting that beautiful mental model of the solution will pay in productivity during the lifetime of the task! 🧘

It gives you some headspace to think about the Why/What which leads to better How

The logical next step of having a good mental model of the solution in the task is to remember why/what you are doing.

It may sounds silly, but when always working on the how it's very easy to lose the meaning of what you are doing. This is crucial when doing an implementation because whatever solution you are tackling right now will have repercussion in the future.

A good example of this is one analysis I had to do that was applied to an EEG time series. While I was ready to code the implementation I realized that this analysis will have to run a ridiculous amount of time (i.e. across many overlapping time window, for many recording, for many participant)!

Here, parallelization on the high performance clusters couldn't be an after-thought otherwise the full analysis would have taken weeks to run!

Thinking about the Why/What also allow you to actually not do some work. If the code doesn't need some optimization because that tasks is exploratory the time spent in opt is wasteful! πŸƒ

It makes you better at triangulating root issues

Clearing one task is great, but clearing a whole slew of current and future tasks is even better.

This happens when a root issue has been identified and properly addressed. To find these root issues, signals from other problems needs to be understood and triangulated.

If tasks/problems are understood only at the surface level, it's much more difficult to be able to pinpoint their common source. By taking the time to document tasks and generated detailed what/why even for yourself, the underlying pattern becomes more obvious!

It unlocks the possibility then to clear root causes which are vastly more useful (and satisfying)! βœ…

So I should write 1000 words essay for all of my tasks?

No, but you should at least stop and take the time to think about each tasks you created for yourself. Always put what you think is critical to solve the problem stated in the task.

Then, periodically revisit the task description and add missing informaition if needs be. If the problem is really thorny, use the task to structure your ideas and to lay down what you know!

Your productivity will improve and the amount of documentaiton generated will be of higher quality! πŸ†

If you have a questions or comment, don't hesitate to shoot me a email at! Also, if you liked the content don't hesitate to subscribe to the newsletter! Β 


Subscribe to Yacine's Machine Learning Help Desk

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.