where to post suggestion for the documentation?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

where to post suggestion for the documentation?

Steve Newcomb
Where should I post a suggestion for a minor clarifying improvement to
the documentation that certainly would have saved me some time
<https://trac.ffmpeg.org/ticket/8944#comment:2>?


_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".
Reply | Threaded
Open this post in threaded view
|

Re: where to post suggestion for the documentation?

Jim DeLaHunt-2
On 2020-11-02 13:42, Steve Newcomb wrote:

> Where should I post a suggestion for a minor clarifying improvement to
> the documentation that certainly would have saved me some time
> <https://trac.ffmpeg.org/ticket/8944#comment:2>?

Thank you for pointing out this omission in the FFmpeg documentation
<https://ffmpeg.org/ffmpeg-protocols.html#pipe>. You are making a good
suggestion about what to add in order to correct that omission:

 > Any number of unnamed output pipes is supported, provided all output
pipes are inherited from a parent process that creates them, allows them
to be inherited by child processes, and then spawns ffmpeg and all the
processes that will read those same pipes.

I think <https://trac.ffmpeg.org/ticket/8944> is a poor place to put
that message, however, because the ticket's description is already
centred around the observations about ffmpeg functionality; observations
which ar ebased on a misunderstanding. That means this ticket will
likely get closed and ignored.

It would be better to have a separate ticket which is centred on the
documentation omission.

Just to set your expectations, however, this project does not seem to
value improving its documentation. Don't be surprised if that ticket
languishes. You could also learn how to edit the documentation, and
submit a patch with the documentation fix to ffmpeg-devel. That patch
might well also languish, because it may not get the sign-off required
for it to be applied. I speak from experience.

As evidence of this attitude, see
<https://trac.ffmpeg.org/ticket/8944#comment:3> on your ticket:

 > FFmpeg's documentation is not a a beginner's course to Unix. Learn to
use your operating system.

Zero concession that the documentation omits useful information. Zero
acknowledgement that the documentation should have a goal to help users
succeed when using FFmpeg. 100% blame on user's ignorance for the obstacle.

As a second-best approach, I've included your suggested paragraph here,
where it will get into the list archives. Maybe someone searching for
help will find your insight that way.

Sorry to be a bearer of bad news. Thank you again for your efforts to
share what you have learned. Many readers of this list appreciate it.

      —Jim DeLaHunt, software engineer, Vancouver, Canada


_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".
Reply | Threaded
Open this post in threaded view
|

Re: where to post suggestion for the documentation?

Steve Newcomb
On 11/2/20 5:04 PM, Jim DeLaHunt wrote:
> > FFmpeg's documentation is not a a beginner's course to Unix. Learn
> to use your operating system.
>
> Zero concession that the documentation omits useful information. Zero
> acknowledgement that the documentation should have a goal to help
> users succeed when using FFmpeg. 100% blame on user's ignorance for
> the obstacle.

Thanks for your kind and consoling words, Jim, and for recognizing that
the response to my suggestion was helpful to nobody, and a poor way to
treat anyone's first attempt to contribute.

I've been using and learning Unix since probably 30 years before the
benighted respondent was born, but I chose not to respond at all. To
deal positively with immature behavior, one must first recognize that
/every /response to /any /behavior /reinforces that behavior/.   (Thank
you, B.F. Skinner, for that vital insight.)

Having made contributions to another of the world's Great Projects,
namely Python, I'm more used to a project culture that emphasizes
usability, and therefore documentation.  The software developers of
Great Projects should not have to shoulder the enormous burden of
supporting usability -- of dealing with the innumerable knowledge
deficiencies (or, in my own case, forgetfulnesses) of their software's
users. (N.B. UX -- user experience -- is now a field unto itself, and
about time, too.) <https://www.youtube.com/watch?v=1Z8gbVnrTfE>

It is no easier to contribute to Python's documentation than it is to
improve Python's technology, but at least it isn't harder. Python
certainly has elevated its documentation effort to co-equal status with
all its other aspects/, and//, overall, Python's documentation
demonstrates phenomenal editorial discipline and uniform excellence,
/even while forever remaining a work in progress/.///I feel satisfaction
in having made minor contributions to it, even though it was not easy to
get my suggestions accepted.  I had to convince the editorial powers,
arguing in terms of their own stated values and goals.

It's a pity that it's apparently so hard to help out with ffmpeg's
documentation, even trivially.  Since I came to ffmpeg so recently, my
perspective allows me to assure you that ffmpeg's documentation is
hellishly inscrutable for anyone who arrives fresh, with a pile of media
data in one hand, a trivial problem in the other, and little experience
with either.  Maybe that's not important to ffmpeg's leading lights, but
it should be.  Even though Ffmpeg is not an end-user application, it
should not excuse itself from having first-class documentation.  Python
isn't an end-user application, either.


/

/
_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".
Reply | Threaded
Open this post in threaded view
|

Re: where to post suggestion for the documentation?

Paul B Mahol
In reply to this post by Jim DeLaHunt-2
On Mon, Nov 2, 2020 at 11:05 PM Jim DeLaHunt <[hidden email]>
wrote:

> On 2020-11-02 13:42, Steve Newcomb wrote:
>
> > Where should I post a suggestion for a minor clarifying improvement to
> > the documentation that certainly would have saved me some time
> > <https://trac.ffmpeg.org/ticket/8944#comment:2>?
>
> Thank you for pointing out this omission in the FFmpeg documentation
> <https://ffmpeg.org/ffmpeg-protocols.html#pipe>. You are making a good
> suggestion about what to add in order to correct that omission:
>
>  > Any number of unnamed output pipes is supported, provided all output
> pipes are inherited from a parent process that creates them, allows them
> to be inherited by child processes, and then spawns ffmpeg and all the
> processes that will read those same pipes.
>
> I think <https://trac.ffmpeg.org/ticket/8944> is a poor place to put
> that message, however, because the ticket's description is already
> centred around the observations about ffmpeg functionality; observations
> which ar ebased on a misunderstanding. That means this ticket will
> likely get closed and ignored.
>
> It would be better to have a separate ticket which is centred on the
> documentation omission.
>
> Just to set your expectations, however, this project does not seem to
> value improving its documentation. Don't be surprised if that ticket
> languishes. You could also learn how to edit the documentation, and
> submit a patch with the documentation fix to ffmpeg-devel. That patch
> might well also languish, because it may not get the sign-off required
> for it to be applied. I speak from experience.
>
> As evidence of this attitude, see
> <https://trac.ffmpeg.org/ticket/8944#comment:3> on your ticket:
>
>  > FFmpeg's documentation is not a a beginner's course to Unix. Learn to
> use your operating system.
>
> Zero concession that the documentation omits useful information. Zero
> acknowledgement that the documentation should have a goal to help users
> succeed when using FFmpeg. 100% blame on user's ignorance for the obstacle.
>
> As a second-best approach, I've included your suggested paragraph here,
> where it will get into the list archives. Maybe someone searching for
> help will find your insight that way.
>
> Sorry to be a bearer of bad news. Thank you again for your efforts to
> share what you have learned. Many readers of this list appreciate it.
>
>
I really wish there are no people like you on this list at all.
Please unsubscribe immediately from this list and never ever come back.

We do not need people that tell bad and untrue things about this project.

Contributing patches is always welcomed but your repeated attacks are not.



>       —Jim DeLaHunt, software engineer, Vancouver, Canada
>
>
> _______________________________________________
> ffmpeg-user mailing list
> [hidden email]
> https://ffmpeg.org/mailman/listinfo/ffmpeg-user
>
> To unsubscribe, visit link above, or email
> [hidden email] with subject "unsubscribe".
_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".
Reply | Threaded
Open this post in threaded view
|

Re: where to post suggestion for the documentation?

Steve Newcomb
The code of conduct provides good advice.
<https://ffmpeg.org/developer.html#Code-of-conduct>
It speaks directly to every sentence you wrote below.  I ask you to read
it and take it to heart.

On 11/3/20 11:10 AM, Paul B Mahol wrote:
> I really wish there are no people like you on this list at all.
> Please unsubscribe immediately from this list and never ever come back.
>
> We do not need people that tell bad and untrue things about this project.
>
> Contributing patches is always welcomed but your repeated attacks are not.
>

_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".
Reply | Threaded
Open this post in threaded view
|

Re: where to post suggestion for the documentation?

Paul B Mahol
On Tue, Nov 3, 2020 at 5:57 PM Steve Newcomb <[hidden email]> wrote:

> The code of conduct provides good advice.
> <https://ffmpeg.org/developer.html#Code-of-conduct>
> It speaks directly to every sentence you wrote below.  I ask you to read
> it and take it to heart.
>
>
I was directing reply not to you but to Jim, who is known to spread malice
and untrue statements on this mailing list.


> On 11/3/20 11:10 AM, Paul B Mahol wrote:
> > I really wish there are no people like you on this list at all.
> > Please unsubscribe immediately from this list and never ever come back.
> >
> > We do not need people that tell bad and untrue things about this project.
> >
> > Contributing patches is always welcomed but your repeated attacks are
> not.
> >
>
> _______________________________________________
> ffmpeg-user mailing list
> [hidden email]
> https://ffmpeg.org/mailman/listinfo/ffmpeg-user
>
> To unsubscribe, visit link above, or email
> [hidden email] with subject "unsubscribe".
_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".
Reply | Threaded
Open this post in threaded view
|

Re: where to post suggestion for the documentation?

FFmpeg-users mailing list
In reply to this post by Steve Newcomb
 Hi Steve and all
This is the second time in as many days that I've had to apologise for the behaviour of people on this mailing list, although I have no standing here other than having been here a long time, and having seen it a lot.
As I said in a message yesterday, this level of spite and hostility is seen as normal and desirable; it happens constantly. This is what these people think is normal discourse between colleagues.
What's amazing is that Paul is listed on ffmpeg.org as a potential contract software engineer, so he's presumably looking for work. I can't imagine that anyone hearing this would go anywhere near the guy.
I am doing my best, as I often have, to be as polite as I can but really, please, hear me: Harald, Paul, Carl, the way you relate to people on this list is emphatically not normal for English-language professional interaction. It is not us who are behaving inappropriately. It is you. The level of venom, malice and hatred is so massively out of proportion to the circumstances that most people would be completely horrified and want nothing to do with you.
I have nothing to gain from saying this so please take it in the spirit in which it is intended. You are damaging yourselves and the project and it is completely unnecessary.
Phil
    On Tuesday, 3 November 2020, 16:56:39 GMT, Steve Newcomb <[hidden email]> wrote:  
 
 The code of conduct provides good advice.
<https://ffmpeg.org/developer.html#Code-of-conduct>
It speaks directly to every sentence you wrote below.  I ask you to read
it and take it to heart.

On 11/3/20 11:10 AM, Paul B Mahol wrote:
> I really wish there are no people like you on this list at all.
> Please unsubscribe immediately from this list and never ever come back.
>
> We do not need people that tell bad and untrue things about this project.
>
> Contributing patches is always welcomed but your repeated attacks are not.
>

_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".  
_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".
Reply | Threaded
Open this post in threaded view
|

Re: where to post suggestion for the documentation?

Carl Zwanzig
In reply to this post by Paul B Mahol

On 11/3/2020 9:07 AM, Paul B Mahol wrote:
> I was directing reply not to you but to Jim, who is known to spread malice
> and untrue statements on this mailing list.

For those of use who aren't privy to everything- what wasn't true? Please
tell us. (Hint- opinion can be neither true nor false.)

 From my limited view, what Jim said makes sense in context, and I can
extrapolate that the gatekeepers to the code really aren't interested in
minor patches from other people, nor fixing or even mentioning problems
identified by other*. The ticket Jim linked
(https://trac.ffmpeg.org/ticket/8944#comment:3) does illustrate this- a
single sentence could easily be added to the docs to warn users of this
behavior but instead Cigaes fights it (possibly taking more time than to
make a patch).

*this may not be true, but it appears that way

AND, even someone skilled in unix operations might not realize that
limitation about pipes (I wouldn't have thought of it and I've been using
BSD unix since 1988). Maybe I don't know "unix" at all.

AND, that might not apply when running on another OS with different pipe
semantics or permissions.


On 11/3/2020 9:20 AM, Phil Rhodes via ffmpeg-user wrote:
> [...] the way you relate to people on this list is emphatically not
> normal for English-language professional interaction. [...] I have
> nothing to gain from saying this so please take it in the spirit in which
> it is intended. You are damaging yourselves and the project and it is
> completely unnecessary.
Selectively quoting, but I agree with all of what Phil said.

Later,

z!
_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".
Reply | Threaded
Open this post in threaded view
|

Re: where to post suggestion for the documentation?

Paul B Mahol
In reply to this post by FFmpeg-users mailing list
On Tue, Nov 3, 2020 at 6:41 PM Phil Rhodes via ffmpeg-user <
[hidden email]> wrote:

>  Hi Steve and all
> This is the second time in as many days that I've had to apologise for the
> behaviour of people on this mailing list, although I have no standing here
> other than having been here a long time, and having seen it a lot.
> As I said in a message yesterday, this level of spite and hostility is
> seen as normal and desirable; it happens constantly. This is what these
> people think is normal discourse between colleagues.
> What's amazing is that Paul is listed on ffmpeg.org as a potential
> contract software engineer, so he's presumably looking for work. I can't
> imagine that anyone hearing this would go anywhere near the guy.
> I am doing my best, as I often have, to be as polite as I can but really,
> please, hear me: Harald, Paul, Carl, the way you relate to people on this
> list is emphatically not normal for English-language professional
> interaction. It is not us who are behaving inappropriately. It is you. The
> level of venom, malice and hatred is so massively out of proportion to the
> circumstances that most people would be completely horrified and want
> nothing to do with you.
> I have nothing to gain from saying this so please take it in the spirit in
> which it is intended. You are damaging yourselves and the project and it is
> completely unnecessary.
>

You first come around spreading venom, malice and hatred and polarizing
FFmpeg project as a whole.
No you are not polite, you are mischievous and are targeting multiple
people at once.

Just leave, if you have nothing constructive to say or help other users or
are not intending to send patches or constructive feedback. And no,
criticizing project out of proportions is not constructive feedback.

Yes. You are putting real problematic user of this mailing list in same
basket with FFmpeg developers and than claiming that all FFmpeg developers
and contributors are behaving like this or even worse that all Unix
community is like this.

What is real your goal to achieve with this?

Do you even use ffmpeg or its libraries at all and how?



> Phil
>     On Tuesday, 3 November 2020, 16:56:39 GMT, Steve Newcomb <
> [hidden email]> wrote:
>
>  The code of conduct provides good advice.
> <https://ffmpeg.org/developer.html#Code-of-conduct>
> It speaks directly to every sentence you wrote below.  I ask you to read
> it and take it to heart.
>
> On 11/3/20 11:10 AM, Paul B Mahol wrote:
> > I really wish there are no people like you on this list at all.
> > Please unsubscribe immediately from this list and never ever come back.
> >
> > We do not need people that tell bad and untrue things about this project.
> >
> > Contributing patches is always welcomed but your repeated attacks are
> not.
> >
>
> _______________________________________________
> ffmpeg-user mailing list
> [hidden email]
> https://ffmpeg.org/mailman/listinfo/ffmpeg-user
>
> To unsubscribe, visit link above, or email
> [hidden email] with subject "unsubscribe".
> _______________________________________________
> ffmpeg-user mailing list
> [hidden email]
> https://ffmpeg.org/mailman/listinfo/ffmpeg-user
>
> To unsubscribe, visit link above, or email
> [hidden email] with subject "unsubscribe".
_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".
Reply | Threaded
Open this post in threaded view
|

Re: where to post suggestion for the documentation?

Jim DeLaHunt-2
In reply to this post by FFmpeg-users mailing list
On 2020-11-03 09:20, Phil Rhodes via ffmpeg-user wrote:

> …I am doing my best, as I often have, to be as polite as I can but really, please, hear me: Harald, Paul, Carl, the way you relate to people on this list is emphatically not normal for English-language professional interaction. It is not us who are behaving inappropriately. It is you. The level of venom, malice and hatred is so massively out of proportion to the circumstances that most people would be completely horrified and want nothing to do with you.
> I have nothing to gain from saying this so please take it in the spirit in which it is intended. You are damaging yourselves and the project and it is completely unnecessary.

+1.

Thank you for stating this, Phil.

      —Jim DeLaHunt, software engineer, Vancouver, Canada

_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".
Reply | Threaded
Open this post in threaded view
|

Re: where to post suggestion for the documentation?

Paul B Mahol
In reply to this post by FFmpeg-users mailing list
On Tue, Nov 3, 2020 at 6:41 PM Phil Rhodes via ffmpeg-user <
[hidden email]> wrote:

>  Hi Steve and all
> This is the second time in as many days that I've had to apologise for the
> behaviour of people on this mailing list, although I have no standing here
> other than having been here a long time, and having seen it a lot.
> As I said in a message yesterday, this level of spite and hostility is
> seen as normal and desirable; it happens constantly. This is what these
> people think is normal discourse between colleagues.
> What's amazing is that Paul is listed on ffmpeg.org as a potential
> contract software engineer, so he's presumably looking for work. I can't
> imagine that anyone hearing this would go anywhere near the guy.
>

This direct attack will be reported to Community Committee to take
immediate action. I was very tolerant against constant and small
provocative attacks by you and other participants of this list.


> I am doing my best, as I often have, to be as polite as I can but really,
> please, hear me: Harald, Paul, Carl, the way you relate to people on this
> list is emphatically not normal for English-language professional
> interaction. It is not us who are behaving inappropriately. It is you. The
> level of venom, malice and hatred is so massively out of proportion to the
> circumstances that most people would be completely horrified and want
> nothing to do with you.
> I have nothing to gain from saying this so please take it in the spirit in
> which it is intended. You are damaging yourselves and the project and it is
> completely unnecessary.
> Phil
>     On Tuesday, 3 November 2020, 16:56:39 GMT, Steve Newcomb <
> [hidden email]> wrote:
>
>  The code of conduct provides good advice.
> <https://ffmpeg.org/developer.html#Code-of-conduct>
> It speaks directly to every sentence you wrote below.  I ask you to read
> it and take it to heart.
>
> On 11/3/20 11:10 AM, Paul B Mahol wrote:
> > I really wish there are no people like you on this list at all.
> > Please unsubscribe immediately from this list and never ever come back.
> >
> > We do not need people that tell bad and untrue things about this project.
> >
> > Contributing patches is always welcomed but your repeated attacks are
> not.
> >
>
> _______________________________________________
> ffmpeg-user mailing list
> [hidden email]
> https://ffmpeg.org/mailman/listinfo/ffmpeg-user
>
> To unsubscribe, visit link above, or email
> [hidden email] with subject "unsubscribe".
> _______________________________________________
> ffmpeg-user mailing list
> [hidden email]
> https://ffmpeg.org/mailman/listinfo/ffmpeg-user
>
> To unsubscribe, visit link above, or email
> [hidden email] with subject "unsubscribe".
_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".
Reply | Threaded
Open this post in threaded view
|

Re: where to post suggestion for the documentation?

Steve Newcomb
In reply to this post by Carl Zwanzig


On 11/3/20 12:53 PM, Carl Zwanzig wrote:
> AND, that [advice about inheriting unnamed pipes] might not apply when
> running on another OS with different pipe semantics or permissions.
Too true.  I don't know.  (I'm using Debian Linux, FWIW.)  Some
all-knowing set of  OS mavens should certainly review and edit the
sentence I wrote before it gets plopped into the documentation.

I must be older than you, Carl.  I began using Solaris Unix in 1980, and
I personally installed Florida State University's very first ethernet at
that time.  A little later I was among the first to install SVR4 on an
80386 (as I recall, it took over 100 diskettes to do it).

Linux is better.  Communities do better work than commercial entities
ever could, and there are good reasons why that is so.

Advice to everyone: Always strengthen and grow your community. Never
weaken or shrink it.  Welcome the stranger.  Celebrate and honor
differences and distinctions.  Bury the hatchet.  Share the ordeal. 
Give credit to the others.  Contribute.  Etc. etc. etc. The payoff is big.


_______________________________________________
ffmpeg-user mailing list
[hidden email]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
[hidden email] with subject "unsubscribe".