I'm torn between two worlds, I have this very intuitive (but intricate) mechanism in a command line tool, and I'm wondering as to what extent I should explain this.
I can go the simple way, not explaining it at all and trust my users to figure it out themselves, but then some users might never discover this particular feature.
I can go the scary way and put a lot of mathematical notation into the help output and the man pages, but then users might think this is too complicated and they might develop an inexplicable fear towards my tool or this particular feature.
How can I address both experimental and, let's say, conservative users (the ones that don't go the extra mile when something isn't explained properly)?
The tool is about date and time arithmetic, in particular calculating durations between two dates and/or times, and formatting the results according to format specs.
My internal design uses a multiplication table like this:
- x d t dt x x x x x d x D x D t x x T x dt x D x S
x is unknown (unparsable) input,
d is a date,
t is a time and
dt is a datetime,
D is a date duration (resolution is 1 day),
T is a time duration (resolution is 1 second), and
S is a time-stamp duration (resolution 1 second).
Now the result depends on the duration type and the format specifiers given, and I'm really lacking a succinct way of explaining this, so I do it by example:
'%d' will return the duration in days (like 12 days) '%w' will return the duration in weeks (like 1 week) '%w %d' will return the duration in weeks and days (like 1 week and 5 days) ... '%S' will return the duration in seconds (e.g. 86464 seconds) '%M' will return the duration in minutes (e.g. 1441 minutes) '%H' will return the duration in hours (e.g. 24 hours) '%H %M %S' will return the duration in hours, minutes and seconds (24h 1m 4s) '%H %S' will return the duration in hours and seconds (24h 64s) ...
I mean I could probably work out what I mean with just these few examples given, but there's no formal explanation or anything in there.
Edit for clarity:
The issue I'm trying to point out is that you can combine any of the flags (for seconds, hours, days, months, etc.) and the program will "intelligently" give you a result. Like
%Y %d would give you a year and the number of days (in the range 0 to 365) whereas
%Y %m %d would give you the days in the range 0 to 30 (because the rest is "captured" in the month)