# explaining/documenting an intricate mechanism

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)?

Details:
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
``````

where `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)

-

I think the best way to approach this is to do the following

1. Give examples of how to call your command line tool
2. List the parameter inputs
3. Explain what the parameters mean

DateCalculator.exe [time1] [time2] [format|opt]

time1 - The first date you want to compare
time2 - The second date you want to compare
format - List all of the different formats
'%d' will return the duration in days (like 12 days)
'%w %d' will return the duration in weeks and days (like 1 week and 5 days)

[opt] means that the formatting is optional. By default the date format is "%d"

Then show examples of how to use the tool and expected results. I don't think users really need to know how the parameters will be multiplied together in your code. Just give them a list of inputs and expected outputs. They will should treat your code as a black box.

Some good real life examples of this is how Microsoft does this for their date time format list and how Wolfram Alpha shows their date calculation.

Essentially show enough examples to show me what is possible out of the tool and tell me that it will accept different combinations. Otherwise you will have to write out every permutation and the users will end up reading 10 of the permutations and think the tool is too complex or they will spend more time looking for the right combo rather than just typing in what date fields they want returned.

-
yes, good points, but what about the sheer number of combinations, I mean I can't put like 200 odd examples in there to demonstrate all possibilities. – hroptatyr Apr 5 '12 at 11:57
+1 for the advice to lose the multiplication table, I now think that's something for the documentation inside the code – hroptatyr Apr 5 '12 at 11:58
Adding 200 examples would be a bit overkill but maybe there is some commonality between the permuations? If it is just date and times, perhaps you could mention that it accepts standard date time formats in the programming language you are writing for? – lifeofmle Apr 5 '12 at 12:25
What about simplfying the inputs to be a simple string of "ymwds" so you can just enter things like "yms" or "m" and it would return "year, month and seconds" or "month" respectively. This also drops out the % sign which may be confusing for ordinary users rather than programmers. – lifeofmle Apr 5 '12 at 14:08
well that still doesn't explain the ranges of the respective specifiers, `ymwd` would give you years, months, weeks, days and seconds, so e.g. 1 year 2 months, 3 weeks, 1 day and 4 seconds; `ymd` on the other hand would "promote" the meaning of `d` to 1 year, 2 months, 22 days. I want to explain/document this very detail – hroptatyr Apr 5 '12 at 14:17