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

Reply via email to