Manual durations

To aid in logging time that isn’t captured by Logseq’s logbook functionality (perhaps because the task was only entered after time had already been spent on it, or the button to start the timer was just never pressed), jogseq supports manually specifying a duration for a task. This is done by adding a time:: property to the task block.

Using the time:: property is perfectly compatible with using the logbook, and the two can be used together to capture all time spent on a task. Once a time:: property is parsed by jogseq, it is converted to a logbook entry anyway (using fake timestamps starting from midnight of the journal’s date). As such, if the parsed journal is written back to the graph, the time:: property will be removed.

If specified, the time:: property should use a human-readable duration shorthand, where h represents hours and m represents minutes. The value can use a mix of both. Seconds are not supported. E.g. time:: 10m, time:: 2h, time:: 1h 30m.

Duration rounding

jogseq will automatically round all task durations.

By default, it rounds durations to five-minute intervals. Any duration more than 90 seconds into the next interval will be rounded up, otherwise it will be rounded down. This helps account for additional time inevitably taken for most tasks outside the span captured by starting and stopping the timer. It also more closely aligns with how work would be logged manually, when not using a timer.

However, if this is not desirable, it is also possible to configure jogseq to round durations to the nearest minute. This allows for more accuracy if the timer is used to capture all time spent on a task. To do this, set the duration_interval setting to 1. See Configuration.

In both configurations, durations under chosen interval will always be rounded up. Durations of 0 are not logged.

Target duration

After parsing a journal, jogseq will display the total duration of all tasks it found, and the difference between that total and a “target duration”. This can be used to see at a glance whether any additional time or tasks need to be entered into the journal before it is logged. By default, the target duration is 7 hours, but this can be configured via the target_duration setting. See Configuration.

Context switching cost

It is well-documented that context switching (i.e. switching between multiple tasks) is detrimental to productivity. It can also be difficult to assign a time cost to it, and track it reliably throughout the day such that it is reflected in a journal’s total duration.

jogseq uses a duration-based scale of context switching costs as a mechanism (albeit a simplistic and imperfect one) to help automatically track this extra time. A switching cost is calculated per task, where shorter tasks have lower switching costs and longer tasks have higher ones, and the total is reported for the journal as a whole. The idea is that switching between multiple quick tasks involves less overhead than switching to or from longer tasks.

The scale used to calculate switching costs can be any range of values, in minutes, that spans no more than 30 minutes in total. For example, it could be 1-15, 0-30, or 45-75, but could not be 1-60. To use the same switching cost for all tasks, specify the same value for both ends of the range, e.g. 5-5. Any task with a duration over an hour will use the maximum switching cost.

By default, the range is 0-0, effectively disabling the feature. To enable it, specify a suitable range via the switching_cost setting. See Configuration.

When a valid range is specified, an estimated overall context switching cost for the journal will always be calculated, reported, and included in the journal’s total duration. But it is not logged to Jira as part of individual tasks. Rather, it will only be logged to Jira if a generic, “miscellaneous” task is present in the journal. This task should be identified by having the misc:: true property. There should only be one such task per journal. Only the first will be recognised, any additional miscellaneous tasks will be ignored and display a warning.

Repetitive tasks

If multiple tasks use the same description, it is possible to nest them under a common parent block and have them inherit their description from it. Each individual task should just leave out a description - only specifying the Jira issue ID. This can be useful in cases where the same process is applied to multiple tasks, such as code review. For example:

- Code review:
    - LATER ABC-123
    - LATER ABC-456
    - LATER ABC-789

In this example, all three tasks (ABC-123, ABC-456, and ABC-789) will be logged to Jira with the “Code review” as the worklog description. The parent block itself will not be logged. Any trailing colon in the parent block’s content will be stripped, but will otherwise be used verbatim.