On 2017-11-29 06:53, Compn wrote:
[...]
Also, someone once observed that common sense is not very common. :-)
sure, but please remember the DOCS are already quite verbose, and
brevity is the soul of wit. so if you can say more with less verbiage
that would be great.
[...]
Also please note that most ffmpeg developers and patch authors are from
around the world , and english may not be their native language.
I'd be happy to work on better wording. I think the obstacle is more
fundamental: there isn't agreement on what to say, or a consensus that
it should be said at all.
I find it interesting that bug fixes and enhancements to the source code
of ffmpeg are approved so much more easily than this patch's bug fixes
and enhancements to the text of ffmpeg.org. This is not a smooth
documentation process.
haha! well let me please explain to you what situation you have gotten
yourself stuck into! :)
the development docs that you want to patch are actually the ffmpeg
project's written rules and policy that governs the whole shebang.
so these are the rules that all devs must agree to within the project.
sure, we bicker about the rules and not everyone follows every rule,
and we have many unwritten rules that we also abide by. which also
causes great strife sometimes when someone thinks a rule is official or
not... look i didnt say it was a good system, it is what we have
evolved into over the years.
the point is that changes to this specific part of the documentation
affects all devs, not just new contributors. so we are more interested
to changes of this document. especially large changes all in one patch.
what your v1 patch has unintentionally done is to change our long
standing ffmpeg policy about patch submission and review. i know this
was not your intention, but you have picked one of the core parts of the
project to modify on your first attempt. :)
What this says to me is that the problems I observe in
ffmpeg.org/developer.html go deeper than wording.
There are architectural problems: this one page is supposed to serve as
both the reference for the project's rules and as a tutorial for new
contributors. The requirements for these two purposes differ.
There are governance problems: rules exist for important parts of the
project, but they are not in writing. Exhibit 1 is that the ffmpeg-devel
list is central to this project, but there is presently zero description
of it in this web page. Exhibit 2 is that the actual practice of the
ffmpeg-cvslog list by several senior developers clearly differs from the
description of it in this page. Exhibit 3 is the absence in this whole
discussion of any reference to any rule-making process and its
decisions, when the patch appears to intrude on policy matters.
There are process problems: while I see lots of activity and appropriate
process for improving the code of the ffmpeg executables, there is not
similar activity or appropriate process for improving the documentation.
I think this thread shows that the patch/review/reject or accept model
used for code doesn't work so well for words.
And then there are the writing problems: broken links, all content under
one @chapter, checklists but no instructions to use the checklists,
missing content, unclear content, and so on.
I came here to try to fix the most severe, easiest to fix bugs in the
docs. I am learning that nothing about ffmpeg.org/developer.html is
going to be easy to fix. I am skeptical that splitting the docs patch
will help.
hope this clears things up. feel free to ask me questions off list, or
we can be found on irc.freenode.net #ffmpeg-devel as well for real
time chat.
tl;dr my suggestions:
1. split docs patch
2. less words, rephrase for brevity
3. welcome to open source team collaboration :)
I appreciate that offer. I will hop on to IRC and off-list email for a
bit, and see if I can find a way forward. Maybe I won't find it.
In the meantime, I don't expect that I will get the cooperation needed
to fix this patch. I think it has been defeated.
But I do appreciate the helpful explanation, and I do appreciate the
welcome to the project. Thank you. Best regards,
—Jim DeLaHunt
--
--Jim DeLaHunt, j...@jdlh.com http://blog.jdlh.com/ (http://jdlh.com/)
multilingual websites consultant
355-1027 Davie St, Vancouver BC V6E 4L2, Canada
Canada mobile +1-604-376-8953
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel
