documentation work

2 files changed, 19 insertions, 22 deletions

diff --git a/README.md b/README.md
index 4f95800..9ba5f16 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 calendar-cli
 ============
 
-Simple command-line CalDav client, for adding and browsing calendar items, todo list items, etc.  As of version 0.11 it's even becoming a full-fledged task management tool.
+Simple command-line CalDav client, making it possible to add calendar events, browse an agenda and doing task management towards a caldav server.
 
 Other tools
 -----------
@@ -111,6 +111,8 @@ In the examples folder there is a task management script which will use the --to
 
 With the todo-command, there are quite some options available (i.e. --categories, --limit, --todo-uid, etc) to select or filter tasks.  Those are used by the commands list, edit, postpone, complete and delete.  A typical use-case scenario is to first use the "list" command, tweak the filtering options to get a list containing the tasks one wants to operate with, and then use either edit, postpone, complete or delete.
 
+The file TASK_MANAGEMENT.md contains some thoughts on how to organize tasks.
+
 Configuration file
 ------------------
 
diff --git a/TASK_MANAGEMENT.md b/TASK_MANAGEMENT.md
index 326c73b..5745235 100644
--- a/TASK_MANAGEMENT.md
+++ b/TASK_MANAGEMENT.md
@@ -1,54 +1,49 @@
 Managing tasks through calendar-cli
 ===================================
 
-While the RFC does draw some lines on what fields are admissable in the todo-entries in the calendar, it doesn't really give good guidelines on how to use the different fields.
+While the RFC does draw some lines on what fields are admissable in the todo-entries in the calendar, it doesn't really give good guidelines on how to use the different fields.  One often gets into dilemmas ... when to use the category field vs when to use the location field vs when to branch out a completely distinct calendar, etc.  This document was originally written for myself, trying to make my own task management consistent and efficient.
 
-As of 2015-04, this document is just a collection of random thoughts on how to organize task lists.  I haven't done much research in how different software packages handles tasks, nor do I have much experience with managing task lists.  Also, calendar-cli is not really ready yet.
+I haven't done much research in how different software packages handles tasks, but I've been using calendar-cli for some task management, the document has been updated with my experiences.
 
 Calendar scope
 --------------
 
-Different categories of tasks can be put into different calendars (and even different caldav servers).
+Different categories of tasks can be put into different calendars (and even on different caldav servers).
 
 I believe it's best to keep as few calendars as possible, and rather use i.e. the categories field for splitting different types of tasks.
 
 As you can give access rights to other people for a whole caldav calendar (or "task list"), it makes sense to use the calendar level to control access rights.  You would typically like to have one calendar where your family can view/add tasks, other for work, perhaps separate calendars for separate projects at work if different projects involves different people, etc.
 
+I have a boat, and it requires a lot of maintenance and attention.  Should I create a separate calendar for boat maintenance tasks?  Considering the thoughts above, what matters is whomelse should have the rights to view and add tasks.  If the boat is a family project, use the same calendar as for other family/home-related todo-tasks.
+
 Location
 --------
 
-A named location.
-
-One thought - some tasks are only possible to do at a specific location.  When being at that location, one would like to list out the pending tasks that applies for that location.
-
-Examples:
+A named location.  TLDR: I've ended up almost never using the location field for tasks.
 
-* As a boat owner, there is always lots of maintenance and improvements work to be done on the boat.  "on the boat" is probably a good location.
-* Other work can be done from home or from the office, some work should be done in the garden, etc.
+With events, the location field is frequently used for which meeting room the meeting should be at, or the address of an appointment.  It's often checked up just before the meeting, or copied to the navigator when one is heading for the appointment.  Tasks are different, if you are at some specific location you would typically like to check up all tasks at that location or in the neighbourhood and see if you can do some of them.
 
-Would it make sense to have a separate calendar for the boat?  If you'd like to share the task list with your family, then I think it can be in the same calendar as other family stuff.
-
-Practical experience: This fits much better into the categories field.
-
-Second thought - some todo-items may need to be done at a specific location.  The address can be added to the location field, so it will be visible when inspecting the event at a later stage.  (I've often had a need for this with events, but not with todo items).
+I had an idea that some tasks are only possible to do at a specific location (i.e. as a boat owner, there are lots of tasks that can only be done "at the boat", some work can be done from home, some work has to be done from the office, some work should be done in the garden, etc), and when being at that location, one would like to list out the pending tasks that applies for that location.  However, practical experience shows that "boat", "office", "home", "garden", "grocery store", "hardware store", etc are better suited as a category than as a location.  Generally, if you have a lot of tasks connected to the same address, probably it's better to do it as a category rather than location.  If the location is a single-off thing used only for that specific task (or, perhaps, some very few tasks) then obviously it's better to use location than category.
 
 Geo
 ---
 
-A geo is a location given by coordinates.  It makes great sense to use geo ...
+A geo is a location given by coordinates.  It probably makes great sense to use geo ...
 
 * if you want to stick the tasks to a map.  Probably very useful if your tasks have to be done on lots of different locations (i.e. if you are a travelling salesman or a plumber).
-* if you want to set up the phone to automatically remind you about tasks i.e. when you are close to the supermarked, etc.
+* if you want to set up the phone to automatically remind you about tasks i.e. when you are close to the supermarked, etc.  (however, most of us probably have several supermarkets we can go to, so geo doesn't make sense for that)
 
 Practical experience: I haven't used the geo field myself.
 
 Categories
 ----------
 
-I'd like to think of categories as tags that can be stuck to tasks.  I.e., some tasks should be done while sitting by the keyboard.  Some tasks are related to a particular project.  Some tasks are best done when the weather is good.  Some tasks has to be done in the day time, others in the evening.  Now, add tags, so that whenever you have the chance to do some task in good weather during the daytime, you can filter out those tasks.
+I'd like to think of categories as tags that can be stuck to tasks, and then used to filter out relevant tasks.  Some tasks should be done while sitting by the keyboard.  Some tasks are related to a particular project.  Some tasks are best done when the weather is good.  Some tasks (i.e. visit some office) has to be done in the "business day time".  Add tags for this and other relevant stuff.  When the sun is shining and you want to do some outdoor tasks, filter out the tasks with categories "sunny" or "garden".
 
 When to use location or geo, and when to use category?  I think that for the super market example, geo is not really fitting because it can only be one geo coordinate related to a vtodo, but there are many super markeds that can be visited.  One could also think that "supermarked" is not a good location for the same reason.  In practice, I've never used location and geo, always been sticking such information into the categories instead.
 
+While the categories field is a freetext field, it's important that the same categories are used consistently.  I made it possible to do "calendar-cli todo list --list-categories" to just take out a list of used categories.
+
 Pending-Dependent
 -----------------
 
@@ -87,7 +82,7 @@ There are two kind of recurrances:
 
 There can be only one status and one complete-date for a vtodo, no matter if it's recurring or not.
 
-Based on my interpretation of the standards, I've implemented logic in calendar-cli task completion code to duplicate the vtodo entry if it has an rrule; one vtodo ends up as completed, the other gets a new timestamp based on the rrule ("next after today".  An rrule may be set up both with fixed-time (as in "every Monday, at 10:00") and with specified intervals ("weekly"), so if you complete the task sunday evening, it will be due again Monday if it's a fixed-time rule and Sunday evening if it's with specified intervals).  The two rrules are linked togheter through the recurrance-id attribute.
+Based on my interpretation of the standards, I've implemented logic in calendar-cli task completion code to duplicate the vtodo entry if it has an rrule; one vtodo ends up as completed, the other gets a new timestamp based on the rrule ("next after today".  An rrule may be set up both with fixed-time (as in "every Monday, at 10:00") and with specified intervals ("weekly"), so if you complete the task sunday evening, it will be due again Monday if it's a fixed-time rule and Sunday evening if it's with specified intervals).  The two rrules are linked togheter through the recurrance-id attribute. (perhaps this logic should be moved from calendar-cli to the caldav library).
 
 There is no support for rrules outside the task completion code, so as for now the rrule has to be put in through another caldav client tool, through the --pdb option or through manually editing ical code.  I believe recurring tasks is an important functionality, so I will implement better support for this at some point.
 
@@ -122,8 +117,8 @@ My usage pattern so far:
 * On a daily basis, look through all tasks that have passed the dtstart timestamp.  I'm considering when/how to do those tasks and (re)consider what is most urgent.  It's important to keep this list short (or it gets unwieldy, demotivating, etc), so I procrastinate everything I know I won't get done during the next few days.  I move the dtstart  timestamp to some future date - depending on my capacity, the importance of the tasks, etc, I add either some few days, weeks, months or years to it.
 * Whenever I think of something that needs to be done, I add it on the task list, immediately, from the telephone.
 * I've been using the timestamps to try to prioritize the tasks.
-* Whenever I'm at some specific location or doing some specific work, I'll filter the task list by category.
+* Whenever I'm at some specific location or doing some specific work, I'll filter the task list by category, often including tasks with future dtstart.
 
 I believe my approach of using timestamps rather than the priority field makes some sense; by looking through the "task list for this week" on a daily basis, and adding some weeks to those I know I won't be able to do anytime soon, the task list is always being circulated, there are no tasks that really gets forgotten.
 
-Task lists tend to always grow, at some point it's important to realize ... "Those tasks are just not important enough ... I'll probably never get done with those tasks", and simply delete them.
+Task lists tend to always grow, at some point it's important to realize ... "Those tasks are just not important enough ... I'll probably never get done with those tasks", and simply delete them.  I'm not so good at that, my alternative approach is to set a due-date and dtstart in the far future.  I remember back in 2005, 2008 was the year I was going to get things done.  Hm, didn't happen. :-)