Start|Stop Timer for Item (Task)

[nelsonic]

Story

As a person wanting to maximise my personal effectiveness,
I want be able to associate (start|stop) a timer with a task (todo list item)
So that I can keep track of how much time I have spent on a given task.

Context

Most people listed "tracking time on a task" as highly desirable feature in #262 ❤️

It has always been one of our core objectives to track time against tasks.
One of the most frustrating things about most task/todo apps is that they don't have this feature!
Not being able to track the time spent on a task leads to people being distracted/unfocussed.
It's incredibly frustrating to work in a team where it's impossible to see what other teammates are working on or how long they has spent on a given task. This is a systematic problem of all "ticketing" systems like JIRA, Trello or Asana. It means everything takes longer than it needs to. Let's fix it.

Given that it's a "core" feature, we already have the Schema in place for attaching timers to items.
It's a one-to-many relationship which means an item can have multiple timers.

This means you can start|stop several timers for a given item and accumulate a total amount of time spent on a task over one or more sessions.

Todo

• Edit the lib/app_web/templates/item/show.html.eex template to
  • Display the item inline instead of in a <ul><li> similar to the TodoMVC UI
• Create the UI <button class="{item.id}-start"> to start & stop a timer for a task.
• Create a <div class="{item.id}-timer"> to display the timer for the task.
  • A timer should appear in the <div> when start button is clicked.
• Create a new test in test/app_web/controllers/timer_controller_test.exs
  • That tests for the insertion of a new timer record in the timers table.
  • The new timer should be linked to an item_id
  • The test should fail before the function is written (because this is new functionality) ...
• Create a new timer entry for the item_id when the start button is pressed.

  In case you are wondering why the timers table has both a start and inserted_at column, it's so that the client can define the start (the time when the timer was started),
  but they cannot define/change the inserted_at (which is controlled by Phoenix/Postgres)
  This is to mitigate "time travelling" (people always "starting" timers in the past) ...
  The client can still define a start in the past, that's "OK" for people who forget to start a timer.
  But the server will still "know" when the timer was actually inserted into the DB.
  So someone waiting till the end of the day to retrospectively start/stop a bunch of timers to make it look like they have been super busy and used their time well will be informed otherwise.
  People who don't use the app to improve their personal effectiveness by starting timers before they start working on a task, but rather invent a bunch of timers for a time-sheet will be flagged.
  Don't mistake this for "big brother" watching you, it's "coach" making you a better teammate!

• Write the (Elixir) start_timer/1 function to be invoked to make the test pass.
• Invoke start_timer/1 when the start button is clicked/tapped.
• Write JavaScript code in that enhances the server-rendered page to:
  • Render a Clock in the form HH:MM:SS in the <div> created above.
    • Only display relevant timer information to keep the UI clean i.e:
      • When only a few seconds have passed show SS e.g: 7, 8, 9, etc.
      • When more than 9 seconds have passed show 10, 11, 12, etc.
      • After a minute has passed, show 1:01, 1:02 etc. where the 0 is now significant.
      • At 9:59 (nine min and fifty-nine sec) add the next digit: 10:00, 10:01, 10:02, etc.
      • Once 59:59 has passed add the first hour digit: 1:00:00
      • Finally if the timer reaches 9:59:59, add the final digit of significance 10:00:00

      Note: this format for displaying the time is subject to discussion/change.
      We just need something for now so that we can ship this feature!
      For now we do not foresee a timer lasting more than 24 hours. (to be tested!)
      But if Goggins starts using our app to time his runs we'll craft a UI just for him!

  • Update the clock each second.
• Create a test for the stop_timer/1 function
• Write the stop_timer/1 function to pass the test
  • stop_timer/1 should Update the timer record with an end value
• Invoke stop_timer/1 when the stop button is clicked in the UI.

Proposed MVP UI/UX

This proposed UI/UX is just to create the MVP functionality.
It will change over time as we use the App and collect feedback.

https://www.figma.com/file/WrpkKGJNYZbeCzMRDVtvQLbC/dwyl-app?node-id=0%3A1

Walkthrough of UI/UX Screens:

1. In this UI we can see a list with 5 items in this case the list.title is "Todo List".

• A start button is displayed on the right of each item

2. When the start for a given item is clicked:

• start button for that item is hidden
• a stop button appears
• Hide the start buttons for all other items (to avoid multiple concurrent timers)
• the timer is displayed above the stop button.
• the timer is updated once per second to show the passing of time.

3. When the stop button for a timer that is running is clicked:

• Hide the stop button
• Stop the timer from counting. (clearInterval(timer))
• Show the start timer

4. If the person clicks/taps the "box" on the left of the item.text to signal that the item is done:

• Update the "box" to the "done" arrow version
• Strikethrough the item.text to show that it is complete (feedback welcome on this UX)
• Hide the start button for this item as it's no longer relevant
• Display the total time taken for the item

Feedback on this issue/spec very much welcome. 🙏
I'm not "precious" about any of it, if you think we can do better UI/UX/functionality, comment!! 💬
I intend to start building it today. Once it's ready for review I will assign the PR. 📦

[SimonLab]

This timer feature sounds good to me.
I have a few questions link to the timer which might help us later on to scope the feature of the application:

• Having only one timer running at a time make it obvious for people to know which task is currently on focus. However can we have tasks that are linked or sub-tasks? In this case multiple timer might be allow to run at same time?

• If it's possible for multiple people to wok on the same task, do we want to display mutliple timers buttons for each of the participant on the task?

• What happen if the user forgot to stop the timer? Do we want to stop the timer automatically after a certain period of time? Do we want to allow people to edit timers?

[nelsonic]

@nelsonic great questions. 👍
This initial implementation of the start|stop functionality is only meant to be super basic.

1. Multiple Timers - While the UI/UX I have (very roughly) sketched out above hides the start button for all other items while there is a timer running for the active item, the API will not impose this restriction at all. Via the API people/clients will be able to start as many concurrent timers as they wish. The concept of linked or sub-tasks is one we need to open a separate issue for. 💡

I think this is the simplest UX for MVP but as noted above, I'm very open to alternatives.
I agree with @iteles's point (made verbally during Zoom Standup call) that it's useful to have the start buttons for other items visible to facilitate rapid task switching. i.e. if a timer is already running, clicking/tapping on the start button of a different item (task) will automatically stop the current task and start the new one. Thus reducing the number of clicks required to switch tasks.
I think this requires further discussion and UX research because it could be argued that not stopping the current task before starting the next one is a "scattered" approach to getting work done. However the counter-argument (and from real-world-experience often the reality of working in an an office where people can walk up to you and interrupt you with a tap on the shoulder) is that being able to context-switch as quickly as possible in the UI/UX is essential for helping people keep track of their distractions/interruptions. 💭 (this should be discussed/debated further in a separate issue)

2. Multiple people working on the same task ... again this requires a separate issue. But the Schema attaches a timer to a person_id which means that it is technically feasible for infinite people to start a timer for the same item. I honestly think we need to keep the UX as simple as possible right now to ship the MVP and then explore how to let people "pair" on a task (which is a simple way to think about more than one person working on a task).

There are definitely several use-cases for multiple people to "wok" on the same task. 🥘 😉
When we explore the idea of scheduled tasks (i.e. calendar item) we will need to allow multiple people to log time against the same item automatically if they are in the same meeting. 🗓

3. Forgetting to either start or stop a timer is something we need to figure out [Epic] Remembering to Start/Stop a Timer for an Activity/Task #221
   It means creating an interface to allow people to edit timers. We will need to do this soon because I expect we will all need the feature. But in order to preserve accountability in the App, we need a transparent way of storing the history of a given timer record. That means re-visiting Postgres History: https://github.com/dwyl/postgres-history-spike which @RobStallion managed to get working last year but we still need to make into an executable Elixir, Python or Node.js module. 💡

Thanks again for your feedback! I will proceed with building this functionality as described above
and will assign a PR for review when ready. 👨‍💻

[iteles]

@nelsonic Thanks for writing this out!
I would note that it won't be worth spending a huge amount of time on the UI side of this because as you say, this will change relatively soon (and probably even before the MVP release). I want to open a separate issue on MVP features and UI for us to start testing.
I've started adding some thoughts to the Figma document and will do more of this asap.

My thoughts on @SimonLab's questions (thank you for these):

• Multiple timers: My personal preference is to only have one timer running at a time because my workflow is made easier by not having to stop timers - most of the time I like to start the next one and have that automatically stop the previous. More on this later.
• Multiple people working on the same task: This is entirely plausible in the sense that each person could be working on one of various sub-tasks or even pairing on a task. Here the key will be (as Nelson mentions above) that each person is running their own timer. How we display this in the team/collaboration mode EPIC: Team Mode #219 is a separate question!
• Other timer functionality: There is a lot that goes into this type of question for me, including the ability to go back in and update timer times. Definitely add your thoughts to [Epic] Remembering to Start/Stop a Timer for an Activity/Task #221 or open a new issue if you feel it doesn't capture everything you are thinking.

[nelsonic]

Timers working on MVP: https://mvp.fly.dev/

[nelsonic]

@iteles please UAT this on the MVP and confirm we have the start|stop working ⏱️
as you would expect from the person using the App? Thanks! 🙏

[nelsonic]

As noted above, start|stop is working in the MVP. ⏱️
@SimonLab has a follow-up task to look at the timer functions: dwyl/mvp#136 🧑‍💻
unpinning this issue. please close when we are confident that it's working in the MVP. Thanks! 🙏