explaining/documenting an intricate mechanism [closed] - user-interface

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
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.
For clarity:
The issue I'm trying to address is that you can combine any of the flags (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).
Example: %Y %d gives 1 year 90 days whereas %Y %w %d gives 1 year 12 weeks 6 days

Answer 1

If you're looking to create help text within the tool itself, look at the help for the linux date command.
Alternatively, you could do something like this:
$ your_app --help
usage: your_app [OPTIONS] [FORMAT]
Returns the elapsed time between blah blah....
FORMAT:
// list formats here
OPTIONS:
--help Display this help text
--help-detailed Display more extensive help text
--help-examples Display example uses
If I were the user, I'd want --help to list all of the options as a reference, and I'd want the man pages to include as much detail as possible. I tend to use --help as a reminder and the man pages as the authoritative reference.
And no matter how well-written the text may be, a few concrete examples are always valuable.