GothenburgBitFactory / GothenburgBitFactory/taskwarrior

Improve the dates and time documentation

Open
#2,147 6 comments 2 reactions 0 assignees View on GitHub
type:docs
Dominant language
C++
Stars
6.1k
Forks
423
Avg merge
1d 19h
Merged PRs (30d)
11

Description

#### Feature request

*** Clearly state the use case.

* What were you doing?
The date management is a huge feature and I needed to know more. I was searching how to fully use dates and time… I googled and found the 4 pages but only checked the first one: https://taskwarrior.org/docs/dates.html, at first.

* What did you expect to happen?
Find the information I needed.

* What actually happened?
It was hard to find it because the date and time information is split on many pages (which is fine) but they are:
— not (all) cross referenced (and the first one I checked was not, but I finally noticed on the google page results that there were many);
— and not well explained (this one explains this, that one that, if you don't want this but that, see that other page).
**Note**. The pages I found:
— using_dates.html: the main page, which is about the different date types, the date meanings;
— dates.html, mainly about the numerical date and time format;
— named_dates.html, about the alphabetical and calculated date and time format, it develop the huge work you made with dates;
— calc.html completes the calculated date paragraph even if examples like *eg* due:"today + 2 days" or scheduled:"november + 1 month" are not given;
— examples.html is quite useful too.

*** Clearly describe the feature.

* What do you suggest?
[Ordered list]
1. Add links on each of the pages to the others, *eg*:
— either at the end in a “See also” section;
— or better at the beginning or in the margin below the table of contents.
(And give, not only links, but also a very small description of the pages *eg* main or types, num_format, named_format).
2. The dates.html page, because of its name, seems to be the main page but is not (and comes first in Google). Rename it may be more messy than useful, so at best, suggest to read first using_dates.html, or at least give using_dates.html as the first link with the “(main page)” description.
3. Add a few examples at the end of the named_dates.html, in the Calculated dates paragraph, *eg* due:"today + 2 days", due:today+1d, scheduled:"november + 1 month", scheduled:november+1m, until:"now + 2 hours", until:now+2h, and next to this paragraph in the margin, suggest to “see also” the Dates paragraph of the calc.html page.
4. Maybe move the Synonyms paragraph of dates.html onto named_dates.html for consistency; that would make in my opinion the named_dates.html the second useful page for dates after using_dates.html; this proposition is not really important but I insist, the named_dates.html is really useful and explains the huge work you made with dates, their names, their calculations.

Finally, as a side comment, I use taskwarrior to manage my appointments. The scheduled date is the beginning and the due date is the end. I add a (sometimes yet empty) location: field to know that this is an appointment and not a “real” task. If this is a recurrent feature request, you may add this workaround somewhere.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.