Format of Effort estimates should be mentioned in its Info node

Format of Effort estimates should be mentioned in its Info node

[Kisaragi Hiu]

Currently, the Info node about effort estimates does not mention what
format should it be written in. This causes confusion, as a user might
assume that it's the same format as schedulers (10m, 6h, etc.) like I
did.

Simply mentioning "Effort estimates need to have the format H:MM"
(copied from the docstring or org-effort-property, the only*
description of the format I could find) in the Info node would be
enough.


*: searching for regexp effort.*format and manually filtering out the other 3 matches

Re: Format of Effort estimates should be mentioned in its Info node

[Kyle Meyer]

Kisaragi Hiu <mail@kisaragi-hiu.com> writes:

> Currently, the Info node about effort estimates does not mention what
> format should it be written in. This causes confusion, as a user might
> assume that it's the same format as schedulers (10m, 6h, etc.) like I
> did.
>
> Simply mentioning "Effort estimates need to have the format H:MM"

I don't personally use effort estimates, but quickly poking around I see
some indication that estimates should work fine with things like 10min
rather than 0:10.  In particular org-set-effort has a bit that looks
like this:

  (org-refresh-property '((effort . identity)
                          (effort-minutes . org-duration-to-minutes))
                        value)

The presence of org-duration-to-minutes hints to some sort of
normalization:

  (org-duration-to-minutes "10min") ; => 10.0
  (org-duration-to-minutes "0:10")  ; => 10.0

And it looks like org-agenda-compare-effort uses the effort-minutes text
property.  That's presumably why, when I view the entries below in the
agenda, org-agenda-filter-by-effort (bound to "_") treats them the same:

  * TODO a
    :PROPERTIES:
    :Effort:  10min
    :END:

  * TODO b
    :PROPERTIES:
    :Effort:   0:10
    :END:

But that's just one use of effort values, and it sounds like you've hit
into cases where the 10min form didn't work as expected.  Could you
provide more details?

> (copied from the docstring or org-effort-property, the only*
> description of the format I could find) in the Info node would be
> enough.

Given the above, it seems like org-effort-property's docstring is at
least somewhat inaccurate.

Re: Format of Effort estimates should be mentioned in its Info node

[Kisaragi Hiu]

It didn't work for me because I gave it "10m" which actually means 10 months, I've realized.

Still, Durations as defined by org-duration.el should be described in the manual like how Timestamps are.

2020年1月4日 11:55 差出し人： kyle@kyleam.com:

> Kisaragi Hiu <mail@kisaragi-hiu.com> writes:
>
>> Currently, the Info node about effort estimates does not mention what
>> format should it be written in. This causes confusion, as a user might
>> assume that it's the same format as schedulers (10m, 6h, etc.) like I
>> did.
>>
>> Simply mentioning "Effort estimates need to have the format H:MM"
>>
>
> I don't personally use effort estimates, but quickly poking around I see
> some indication that estimates should work fine with things like 10min
> rather than 0:10.  In particular org-set-effort has a bit that looks
> like this:
>
> (org-refresh-property '((effort . identity)
> (effort-minutes . org-duration-to-minutes))
> value)
>
> The presence of org-duration-to-minutes hints to some sort of
> normalization:
>
> (org-duration-to-minutes "10min") ; => 10.0
> (org-duration-to-minutes "0:10")  ; => 10.0
>
> And it looks like org-agenda-compare-effort uses the effort-minutes text
> property.  That's presumably why, when I view the entries below in the
> agenda, org-agenda-filter-by-effort (bound to "_") treats them the same:
>
> * TODO a
> :PROPERTIES:
> :Effort:  10min
> :END:
>
> * TODO b
> :PROPERTIES:
> :Effort:   0:10
> :END:
>
> But that's just one use of effort values, and it sounds like you've hit
> into cases where the 10min form didn't work as expected.  Could you
> provide more details?
>
>> (copied from the docstring or org-effort-property, the only*
>> description of the format I could find) in the Info node would be
>> enough.
>>
>
> Given the above, it seems like org-effort-property's docstring is at
> least somewhat inaccurate.
>

Re: Format of Effort estimates should be mentioned in its Info node

[Jean-Christophe Helary]

> On Jan 4, 2020, at 14:20, Kisaragi Hiu <mail@kisaragi-hiu.com> wrote:
> 
> It didn't work for me because I gave it "10m" which actually means 10 months, I've realized.
> 
> Still, Durations as defined by org-duration.el should be described in the manual like how Timestamps are.

This does look like a potential contribution to the package.

Jean-Christophe Helary

> 
> 2020年1月4日 11:55 差出し人： kyle@kyleam.com:
> 
>> Kisaragi Hiu <mail@kisaragi-hiu.com> writes:
>> 
>>> Currently, the Info node about effort estimates does not mention what
>>> format should it be written in. This causes confusion, as a user might
>>> assume that it's the same format as schedulers (10m, 6h, etc.) like I
>>> did.
>>> 
>>> Simply mentioning "Effort estimates need to have the format H:MM"
>>> 
>> 
>> I don't personally use effort estimates, but quickly poking around I see
>> some indication that estimates should work fine with things like 10min
>> rather than 0:10.  In particular org-set-effort has a bit that looks
>> like this:
>> 
>> (org-refresh-property '((effort . identity)
>> (effort-minutes . org-duration-to-minutes))
>> value)
>> 
>> The presence of org-duration-to-minutes hints to some sort of
>> normalization:
>> 
>> (org-duration-to-minutes "10min") ; => 10.0
>> (org-duration-to-minutes "0:10")  ; => 10.0
>> 
>> And it looks like org-agenda-compare-effort uses the effort-minutes text
>> property.  That's presumably why, when I view the entries below in the
>> agenda, org-agenda-filter-by-effort (bound to "_") treats them the same:
>> 
>> * TODO a
>> :PROPERTIES:
>> :Effort:  10min
>> :END:
>> 
>> * TODO b
>> :PROPERTIES:
>> :Effort:   0:10
>> :END:
>> 
>> But that's just one use of effort values, and it sounds like you've hit
>> into cases where the 10min form didn't work as expected.  Could you
>> provide more details?
>> 
>>> (copied from the docstring or org-effort-property, the only*
>>> description of the format I could find) in the Info node would be
>>> enough.
>>> 
>> 
>> Given the above, it seems like org-effort-property's docstring is at
>> least somewhat inaccurate.
>> 
> 
> 

Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: Format of Effort estimates should be mentioned in its Info node

[Nicolas Goaziou]

Hello,

Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
writes:

>> On Jan 4, 2020, at 14:20, Kisaragi Hiu <mail@kisaragi-hiu.com> wrote:
>> 
>> It didn't work for me because I gave it "10m" which actually means 10 months, I've realized.
>> 
>> Still, Durations as defined by org-duration.el should be described in the manual like how Timestamps are.
>
> This does look like a potential contribution to the package.

I'm not sure would be pertinent to create a whole section for duration
format: these are not quite as ubiquitous as timestamps. However, they
are used here and there so it may be better to add a few words in the
appropriate sections, the main one being obviously "Effort Estimates".

Anyway, patches welcome! :)


Regards,

-- 
Nicolas Goaziou

Re: Format of Effort estimates should be mentioned in its Info node

[Bastien]

Hi Jean-Christophe,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> I'm not sure would be pertinent to create a whole section for duration
> format: these are not quite as ubiquitous as timestamps. However, they
> are used here and there so it may be better to add a few words in the
> appropriate sections, the main one being obviously "Effort Estimates".
>
> Anyway, patches welcome! :)

would you be willing to follow Nicolas' suggestion and send a patch
to enhance the "Effort Estimates" section?

Thanks in advance,

-- 
 Bastien

Re: Format of Effort estimates should be mentioned in its Info node

[Bastien]

Hi Kisaragi Hiu,

Kisaragi Hiu <mail@kisaragi-hiu.com> writes:

> Currently, the Info node about effort estimates does not mention what
> format should it be written in. This causes confusion, as a user might
> assume that it's the same format as schedulers (10m, 6h, etc.) like I
> did.
>
> Simply mentioning "Effort estimates need to have the format H:MM"
> (copied from the docstring or org-effort-property, the only*
> description of the format I could find) in the Info node would be
> enough.

Yes.  Can you submit a patch against doc/org-manual.org?

Thanks!

-- 
 Bastien

Re: Format of Effort estimates should be mentioned in its Info node

[Kisaragi Hiu]

[-- Attachment #1: Type: text/plain, Size: 1254 bytes --]

Done; I haven't done the copyright assignment paperwork with FSF, but I guess it's fine since this is under the 15 line limit?

I copied a few examples from org-duration.el, which is what actually defines the format (org-refresh-effort-estimates). I also corrected the docstring of org-effort-property, as the format does actually allow for values like "10min" or "6h". (I was under the impression that "10m" didn't work because it didn't show up when I asked the agenda to filter to < 60 minutes; it's actually working just fine since that means 10 months.)


2020年2月1日 17:24 差出し人： bzg@gnu.org:

> Hi Kisaragi Hiu,
>
> Kisaragi Hiu <mail@kisaragi-hiu.com> writes:
>
>> Currently, the Info node about effort estimates does not mention what
>> format should it be written in. This causes confusion, as a user might
>> assume that it's the same format as schedulers (10m, 6h, etc.) like I
>> did.
>>
>> Simply mentioning "Effort estimates need to have the format H:MM"
>> (copied from the docstring or org-effort-property, the only*
>> description of the format I could find) in the Info node would be
>> enough.
>>
>
> Yes.  Can you submit a patch against doc/org-manual.org?
>
> Thanks!
>
> -- 
> Bastien
>


[-- Attachment #2: 0001-org-manual.org-Mention-the-format-of-effort-estimate.patch --]
[-- Type: text/x-patch, Size: 1331 bytes --]

From 558ad170a05bb9aaf43e246918cea44d8f8da783 Mon Sep 17 00:00:00 2001
From: Kisaragi Hiu <mail@kisaragi-hiu.com>
Date: Sun, 2 Feb 2020 00:04:23 +0800
Subject: [PATCH 1/2] org-manual.org: Mention the format of effort estimates

* doc/org-manual.org (Effort Estimates): Mention the format of effort
estimates.
---
 doc/org-manual.org | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index ce4fedb55..70a654647 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -6899,9 +6899,14 @@ to produce offers with quotations of the estimated work effort, you
 may want to assign effort estimates to entries.  If you are also
 clocking your work, you may later want to compare the planned effort
 with the actual working time, a great way to improve planning
-estimates.  Effort estimates are stored in a special property
-=EFFORT=.  You can set the effort for an entry with the following
-commands:
+estimates.
+
+Effort estimates are stored in a special property =EFFORT=.  Multiple
+formats are supported, such as =3:12=, =1:23:45=, or =1d3h5min=; see
+the file =org-duration.el= for more detailed information about the
+format.
+
+You can set the effort for an entry with the following commands:
 
 - {{{kbd(C-c C-x e)}}}  (~org-set-effort~) ::
 
-- 
2.25.0


[-- Attachment #3: 0002-org.el-Correct-docstring.patch --]
[-- Type: text/x-patch, Size: 887 bytes --]

From e7e7a3205ae6da51a696f45d7afee5f8b98bddac Mon Sep 17 00:00:00 2001
From: Kisaragi Hiu <mail@kisaragi-hiu.com>
Date: Sun, 2 Feb 2020 00:08:10 +0800
Subject: [PATCH 2/2] org.el: Correct docstring

* lisp/org.el (org-effort-property): Correct docstring, as the
previous description of the format was inaccurate.
---
 lisp/org.el | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/lisp/org.el b/lisp/org.el
index 3605460f3..ba34ee38e 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -565,7 +565,8 @@ An entry can be toggled between COMMENT and normal with
 
 (defconst org-effort-property "Effort"
   "The property that is being used to keep track of effort estimates.
-Effort estimates given in this property need to have the format H:MM.")
+Effort estimates given in this property need to be in the format
+defined in org-duration.el.")
 
 ;;;; Timestamp
 
-- 
2.25.0

Re: Format of Effort estimates should be mentioned in its Info node

[Bastien]

Hi Kisaragi Hiu,

> Done; I haven't done the copyright assignment paperwork with FSF, but
> I guess it's fine since this is under the 15 line limit?

Yes, thanks a lot.  I've applied your commits to th master branch.  I
just added the TINYCHANGE cookie in the commit messages.

> I copied a few examples from org-duration.el, which is what actually
> defines the format (org-refresh-effort-estimates). I also corrected
> the docstring of org-effort-property, as the format does actually
> allow for values like "10min" or "6h". (I was under the impression
> that "10m" didn't work because it didn't show up when I asked the
> agenda to filter to < 60 minutes; it's actually working just fine
> since that means 10 months.)

Thanks again!

-- 
 Bastien