Subject: Re: bug#32533: my documentation improvement proposals are in most cases not answered

From: Assaf Gordon <[email-masked]>
Date: Sun, 26 Aug 2018 19:36:56 -0600

Hello,

On 25/08/18 12:46 PM, kalle wrote:
> I mostly read info- and man-documentation of elementary GNU-programs
>  and here and then send a bug-report on this documentation, if I 
> consider it bad or improvable.

Thank you for sending those - we do appreciate and suggestions and
contributions, even if it takes time to respond to them.

> While I was often really motivated to help improving free software,
> I sometimes think now that my work is not considered useful and this
>  tends to diminish my motivation sometimes.
> 

It can certainly be frustrating when topics seem to linger on or
"fall between the cracks".

But please remember that GNU coreutils maintainers are volunteers,
and work is done on "best effort" cases, often depending on priority
(e.g. critical bug vs a minor documentation change), available time,
and readiness of changes (e.g. if a patch is provided).

> Looking at my bug-reports on coreutils' bug-list 
> (https://debbugs.gnu.org/cgi/pkgreport.cgi?which=submitter&data=kalle%40projektwerkstatt.de)
 >
> I see that from 7 reports i sent, 3 didn't get any answer 
> (29316,32250,32464), two got closed by padraig just after answering 
> my mail (29315,31712), such that I couldn't react appropriately,one 
> was discussed and rejected, where I had the impression, that there 
> was no real will to make improvement (29069). And one (27136) was 
> reacted to, but without having found a real solution. >

Here are some concrete suggestions to help facilitate faster and more 
effective process:

1.
In the case of https://bugs.gnu.org/27136 - There was a clear reply from 
Pádraig, followed by further explanation by Paul:
It is a low-priority issue that is not specific to 'cat'.
Therefore, if you want to suggest a specific word change, please do so
by sending a concrete patch.

Being a low-priority issue, other coreutils maintainers have not yet 
shown interest in investing time to change the documentation.

This will be a recurring theme:
Sending a concrete patch makes it much easier for maintainers to
incorporate changes. If you want to promote documentation changes in an
effective way, please do send patches with specific word changes.

2.
In the case of https://bugs.gnu.org/29316 ,
https://bugs.gnu.org/32250 ,
https://bugs.gnu.org/32464 ,
It is indeed not very welcoming not to get any responses - we should
always strive to do better.
However, the response to all three is similar to the previous one:
As general suggestions go, these are likely good suggestions.
But they are low-priority and making them into concrete changes require
investing time that currently maintainers do not have.

If you want to promote any of the above, please do prepare a
patch with the word changes you suggest.

3.
In the case of https://bugs.gnu.org/29315 ,
A fix was committed to the code at
https://git.savannah.gnu.org/cgit/coreutils.git/commit/?id=f17c1df39 ,
and other comments have been answers in the email - which is why the bug
report was marked as "done". You are still able to reply and add
information to the bug (and you did).

4.
In the case of https://bugs.gnu.org/31712 ,
I suspect that it was simply a typo, instead of referring
to "-a" it should have been "-p" (same as "--preserve"),
which is mentioned in the documentation.
You'd like needed to write:
   cp --attributes-only --preserve=timestamp FILE OTHERFILE

====

If you'd like to send patches, a good starting point
are these two documents:
http://git.savannah.gnu.org/cgit/coreutils.git/tree/HACKING
http://git.savannah.gnu.org/cgit/coreutils.git/tree/README-hacking

I'm marking this item as "done", since it is not a bug by itself.
Discussion can continue by replying to this thread.

regards,
  - asssaf