From Bayle Shanks:
(1) This situation has exposed a very important need: at least
for some fraction of the computation, a user
needs to be able to sit down next to the NRP and be able to follow
along with its arithmetic, whether with a hand calculator or a
spreadsheet.
Otherwise, they'll quite sensibly start by making their
own spreadsheet to test their understanding, and then if they see that
it differs from the NRP's answer, they'll realize that they can't
further look inside the NRP without help, and default to using the
spreadsheet for the time being.
Imo serving this use case is a priority. I hadn't realized this until
now.
(2) as Bob says, having the software explain what it is doing is much
easier than allowing the user to alter the software's calculation with
mathematical operators. And having the software explain already
fulfills the need in (1). So imo Bob's (A) should be prioritized, and
(B) should be postponed for later.
(3) Bob mentions 'logs'. I think this is exactly the way to go. The
software should (optionally, only for those who want it) spit out
something along the lines of:
Sum of hours by person and activity type:
Abran:
R&D:
* 7/2/2015 2.3 hrs of General Product design to process "Design considerations to R&D plan for
PV characterization starting 2015-06-16 ending 2015-06-30",
note "Finalized recommendations on rotary encoders. Presented
materials and updated milestone 1 official documents with
it."
* ...
total hrs for Milestone 1::Abran::R&D = sum of the above = 10.3
Outreach:
* ..
* ..
total hrs ..: ...
rate per hr..: ...
Bruce:
...
...
Milestone 1 summary:
R&D:
total hrs = Abran's 10.3 + Bruce's ... + ... = 42.43
(total hrs for all activities = 42.43 (R&D) + 24.5 (Outreach) + ...
= 122.92)
proportion of work done = total hrs / total hrs for all activities
= 42.43 / 122.92 = .3452
rate per hour for Milestone 1 :: R&D = $30/hr
(from http://..URL_within_NRP_where_this_parameter_is_set..)
total $ reward = 42.43 * 30 = 1272.90
...
...etc...
(4) Some things to note about the example in (3):
(A) The key is that the arithmetic is printed out, eg
"42.43 / 122.92 = .3452". This is what allows the user to follow
along with their hand calculator or spreadsheet.
(B) Notice that control flow, including graph queries, is not
explicit but merely implicit. The end results of queries are
enumerated explicitly, but most importantly arithmetic is explicit.
Imo the arithmetic is more important to display than how the graph
was queried.
(C) Note that there are not formal mathematical formulae in the
above more complicated than arithmetic. I even said "sum of"
instead of capital Sigma. There is no certaintly no attempt to
provide explicit formal graph queries.
(D) If i understand correctly, this is similar to what the Details
Sandbox already does, but slightly more detailed, as the goal here
is to print out EVERY intermediate arithmetic operation.
(E) That being said, with complicated nested (recursive)
calcuations (eg if a payment is propagating back through multiple
projects who used consumed each others' products), i imagine that
it would be sometimes be desirable to cut off the recursion and
only show one project at a time, eg for the user to opt to start
the trace with "Money coming in from upstream (computation
omitted): $222" and to have lines like:
"total money going to Sub-Project Z (distribution omitted): $111"
From Bayle Shanks: (1) This situation has exposed a very important need: at least for some fraction of the computation, a user needs to be able to sit down next to the NRP and be able to follow along with its arithmetic, whether with a hand calculator or a spreadsheet.
Otherwise, they'll quite sensibly start by making their own spreadsheet to test their understanding, and then if they see that it differs from the NRP's answer, they'll realize that they can't further look inside the NRP without help, and default to using the spreadsheet for the time being.
Imo serving this use case is a priority. I hadn't realized this until now.
(2) as Bob says, having the software explain what it is doing is much easier than allowing the user to alter the software's calculation with mathematical operators. And having the software explain already fulfills the need in (1). So imo Bob's (A) should be prioritized, and (B) should be postponed for later.
(3) Bob mentions 'logs'. I think this is exactly the way to go. The software should (optionally, only for those who want it) spit out something along the lines of:
Milestone 1 per member:
Parameters: Activity types: R&D, Outreach, ... Hourly rates per activity types: R&D: 30 Outreach: ... ...
Sum of hours by person and activity type: Abran: R&D: * 7/2/2015 2.3 hrs of General Product design to process "Design considerations to R&D plan for PV characterization starting 2015-06-16 ending 2015-06-30", note "Finalized recommendations on rotary encoders. Presented materials and updated milestone 1 official documents with it." * ... total hrs for Milestone 1::Abran::R&D = sum of the above = 10.3 Outreach: * .. * .. total hrs ..: ... rate per hr..: ... Bruce: ...
... Milestone 1 summary: R&D: total hrs = Abran's 10.3 + Bruce's ... + ... = 42.43 (total hrs for all activities = 42.43 (R&D) + 24.5 (Outreach) + ... = 122.92) proportion of work done = total hrs / total hrs for all activities = 42.43 / 122.92 = .3452 rate per hour for Milestone 1 :: R&D = $30/hr (from http://..URL_within_NRP_where_this_parameter_is_set..) total $ reward = 42.43 * 30 = 1272.90 ...
...etc...
(4) Some things to note about the example in (3): (A) The key is that the arithmetic is printed out, eg "42.43 / 122.92 = .3452". This is what allows the user to follow along with their hand calculator or spreadsheet.
(B) Notice that control flow, including graph queries, is not explicit but merely implicit. The end results of queries are enumerated explicitly, but most importantly arithmetic is explicit. Imo the arithmetic is more important to display than how the graph was queried.
(C) Note that there are not formal mathematical formulae in the above more complicated than arithmetic. I even said "sum of" instead of capital Sigma. There is no certaintly no attempt to provide explicit formal graph queries.
(D) If i understand correctly, this is similar to what the Details Sandbox already does, but slightly more detailed, as the goal here is to print out EVERY intermediate arithmetic operation.
(E) That being said, with complicated nested (recursive) calcuations (eg if a payment is propagating back through multiple projects who used consumed each others' products), i imagine that it would be sometimes be desirable to cut off the recursion and only show one project at a time, eg for the user to opt to start the trace with "Money coming in from upstream (computation omitted): $222" and to have lines like: "total money going to Sub-Project Z (distribution omitted): $111"