--- Begin Message ---
|
Subject: |
my documentation improvement proposals are in most cases not answered |
|
Date: |
Sat, 25 Aug 2018 20:46:47 +0200 |
|
User-agent: |
Mozilla/5.0 (X11; Linux i686; rv:52.0) Gecko/20100101 Thunderbird/52.6.0 |
hello,
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. I'm especially interested in making documentation
newbie-friendlier in a way, that concepts written about are referenced,
and I would also like to see language usage becoming easier (maybe in
the direction of 'simple english'), but I didn't do anything on the
latter yet.
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.
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.
greetings,
kalle
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#32533: my documentation improvement proposals are in most cases not answered |
|
Date: |
Sun, 26 Aug 2018 19:36:56 -0600 |
|
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.9.1 |
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
--- End Message ---