Time Tortoise: Daily Summary File

This is one in a series of articles about Time Tortoise, a Universal Windows Platform app for planning and tracking your work schedule. For more on the development of this app and the ideas behind it, see my Time Tortoise category page.

I’m working on a text file user interface for Time Tortoise. For the last two weeks, I have focused on file input for program settings. Now I’m moving on to file output.

Daily Summary File

The Time Tortoise graphical UI shows a number of real-time statistics, including how long the active timer has been running, how long the user has been idle, and how much time has been spent on each activity. This view is useful for keeping an eye on how things are going throughout the day.

But it’s also useful at the end of the day to have a summary of the day’s activity. As I have mentioned before, it’s a lot easier to build and update a text file than a GUI. It’s also easier to get data from a text file into another application, like a spreadsheet.

So the idea is to output a daily summary text file.

File Contents

Here’s the most basic information required for the daily summary file:

• A title, to identify the purpose of the file. This should be configurable in the settings file.
• The date of the file. There should be one summary file per day.
• The total time for each task worked that day.
• The total time for all tasks worked that day.
• The date and time the file was last updated.

File Name and Location

In keeping with the philosophy of the text file UI, the daily summary files should be stored in a way that facilitates navigation with a standard text editor. With that in mind, the design is as follows:

• A folder called Daily under %LocalAppData%\Packages\[package_name]\LocalState (the same place the database and settings files are located) will contain the daily summary files.
• Under Daily will be a folder for each month, named in yyyy-mmmm format (e.g., 2017-September).
• In each month folder, daily files will be named in yyyymmdd.txt format (e.g., 20170921.txt).

The purpose of the naming format is to make it easy to find the file for a particular day, and to group together files that cover similar time periods.

File Format

I used the YAML file format for the settings file, since that file is intended to be authored by the user and read by the computer. The daily summary file works in the opposite direction: it’s written by the computer, based on data collected by the time tracker, and read by the user. So it should be optimized for human readability. That means there’s no fixed format. It can contain any information that’s useful, in a format that is most understandable to humans.

Here’s one exception: In my pre-Time Tortoise time tracking process, I used a spreadsheet to calculate summary statistics. It may still be useful to copy Time Tortoise data into a spreadsheet, so I’m considering writing some sections of the daily summary file in tab-separated value (TSV) format, since when TSV-formatted text is pasted into a spreadsheet, it automatically flows into columns.

Writing the File

Although this post describes a daily summary file, there’s no need to wait for the end of the day to write the file. It’s preferable to have it be up-to-date throughout the day. However, it doesn’t need to be accurate up to the second, the way the GUI is. That would mean writing a file to disk every second, which would be wasteful. Instead, it makes sense to write it:

• On the order of once per minute (configurable) while the activity timer is running.
• Whenever something happens that might affect the data, like an activity starting or stopping or a time segment being edited, but not whenever the timer tick fires.

Day Rollover and Previous Days

Two cases to watch out for: the transition from one day to the next, and editing data from days previous to the current day.

When we cross a midnight boundary, we need to ensure that the previous day’s file gets a final update, and the next day’s file gets created. And since it’s possible for the user to edit time segments from previous days, we need to ensure that the appropriate daily summary file gets updated in those cases.

Other Ideas

That should be enough functionality for a useful first cut of the feature, but here are some ideas for future enhancements:

• Create two daily files: the one described above (an output file), and another one that the user can use for daily notes (an input file). Whenever the output file is refreshed, merge the input file into a specific section in the output file. This will produce a daily summary with both statistics from the time tracker, and free-form text that the user can use to record task-related notes for the day.
• Create a target input file in which the user can define time goals (e.g., “spend one hour per day on activity A”). Both the Time Tortoise GUI and the daily summary file can use these target values to report progress against goals.
• In addition to the daily summary file, write weekly, monthly, and yearly summary files.

(Image credit: Dafne Cholet)