[FFmpeg-devel] Development process for explaining contexts (was Re: [PATCH v6 1/4] doc: Explain what "context" means)

[Stefano Sabatini]

On date Sunday 2024-06-16 19:02:51 +0100, Andrew Sayers wrote:
> Meta note #1: I've replied in this thread but changed the subject line.
> That's because it needs to stay focussed on solving this thread's problem,
> but may be of more general interest.
> 
> Meta note #2: Stefano, I appreciate your feedback, but would rather wait
> for [1] to get sorted out, then formulate my thoughts while writing a new
> version.  That way I'll be more focussed on ways to improve things for readers.
> 
> This thread started with what I thought was a trivia question[1] -
> what is a context?  It's short for "AVClass context structure", which is
> synonymous with "AVOptions-enabled struct".  It turned out to be more complex
> than that, so I wrote a little patch[3] explaining this piece of jargon.
> But it turned out to be more complex again, and so on until we got a 430-line
> document explaining things in voluminous detail.
> 
> Everyone agrees this isn't ideal, so here are some alternatives.
> This may also inspire thoughts about FFmpeg development in general.
> 
> # Alternative: Just give up
> 
> The argument: We tried something, learnt a lot, but couldn't find a solution
> we agreed on, so let's come back another day.
> 
> Obviously this is the easy way out, but essentially means leaving a critical
> bug in the documentation (misleads the reader about a fundamental concept).
> Even the most negative take on this document is that it's better than nothing,
> so I think we can rule this one out.
> 
> # Err on the side of under-communicating
> 
> The argument: this document is on the right tracks, but explains too many things
> the reader can already be assumed to know.
> 
> This argument is more complex than it appears.  To take some silly examples,
> I'm not going to learn Mandarin just because FFmpeg users can't be assumed to
> speak English.  But I am willing to use American spelling because it's what
> more readers are used to.  This e-mail is plenty long enough already, so
> I'll stick to some high-level points about this argument.
> 
> The main risk of cutting documentation is that if someone can't follow a single
> step, they're lost and don't even know how to express their problem.  Imagine
> teaching maths to children - you need to teach them what numbers are, then how
> to add them together, then multiplication, then finally exponents.  But if you
> say "we don't need to teach numbers because kids all watch Numberblocks now",
> you'll cover the majority of kids who could have worked it out anyway, and
> leave a minority who just give up and say "I guess I must be bad at maths".
> I'd argue it's better to write more, then get feedback from actual newbies and
> cut based on the evidence - we'll get it wrong either way, but at least this way
> the newbies will know what they want us to cut.
> 
> Incidentally, there's a much stronger argument for *drafting* a long document,
> even if it gets cut down before it's committed.  FFmpeg has lots of undocumented
> nuances that experts just know and newbies don't know to ask, and this thread is
> full of instances where writing more detail helped tease out a misunderstanding.
> [1] is a great example - I had finally written enough detail to uncover my
> assumption that all AVOptions could be set at any time, then that thread
> taught me to look for a flag that tells you the options for which that's true.
> 
> If you assume I'm not the only person who has been subtly misled that way,
> you could argue it's better to commit the long version.  That would give readers
> more opportunities to confront their own wrong assumptions, instead of reading
> something that assumed they knew one thing, but let them keep believing another.
> The obvious counterargument is that we should...
> 
> # Spread the information across multiple documents
> 
> The argument: this document puts too much information in one place.  We should
> instead focus on making small patches that put information people need to know
> where they need to know it.
> 
> This is where things get more interesting to a general audience.
> 
> If you have repo commit access, you're probably imagining a workflow like:
> write a bunch of little commits, send them out for review, then commit them
> when people stop replying.  Your access is evidence that you basically know how
> things work, and also lets you make plans confident in the knowledge that
> anything you need committed will make it there in the end.
> 
> My workflow is nothing like that.  This thread has constantly reinforced that I
> don't understand FFmpeg, so it's better for me not to have commit access.  But
> that means I can only work on one patch at once, because I will probably learn
> something that invalidates any other work I would have done.  It also means
> a single patch not getting interest is enough to sink the project altogether.
> I can put up with that when it's one big multi-faceted patch, because I can work
> on one part while waiting for feedback on another part.  But my small patches
> generally involve a few hours of work, a week of waiting, a ping begging for
> attention, then often being rejected or ignored.  In the real world, the only
> thing this approach will achieve is to burn me out.
> 
> It might be possible to revisit this idea *after* committing the document,
> when we're fairly confident the answers are right and just need to tweak
> the presentation based on feedback.  Or other people could write documentation
> based on issues brought up in this thread, and I'll cut as appropriate.
> But for now this is a non-starter.
> 
> # Write a blog post
> 
> The argument: doxygen and texinfo are good for documenting "timeless truths".
> But we don't have anywhere to put transitory information like upgrade guides,
> or subjective information like guidance about best practices.  This document
> shoehorns information in here that really belongs somewhere like that.
> 
> This is basically true, but that doesn't solve anything.
> 
> I have neither a personal blog nor the desire to write one, and even if I wrote
> an excellent guide to contexts as a general concept, nobody would actually find
> the blog to read it.  So this idea would only work if we e.g. overhauled the
> news area of the site[4] to look more like GIMP's news section[5].
> 
> If someone else would like to start a project like that, I can promise a good
> series of posts to help get the ball rolling, and will be happy to trim down
> the document as those posts go public.
> 
[...]
> # Rewrite the API
> 
> The argument: instead of writing a bunch of words apologising for an interface,
> just write a better interface.
> 
> In general, I'm a big believer in using documentation to drive API decisions.
> But in FFmpeg's case, it wouldn't help to have a single developer trying to fix
> a community-wide problem.
> 

> We've previously discussed swr_alloc_set_opts() (essentially two functions
> sharing one symbol) and av_ambient_viewing_environment_create_side_data()
> (receives a different context argument than its function name).
> A better example of the community-wide issue might be av_new_packet()
> (initializes but does not allocate, despite slightly confusing documentation)
> vs. av_new_program() (allocates and initializes, but has no documentation).
> Both of these could be documented better, and a developer who only needs to

> learn one won't be bothered by the other.  But the real problem is that they
> use the word "new" to mean fundamentally incompatible things, creating a trap
> for anyone reviewing code that uses the "new" they haven't seen before.
> 
> Solving this problem wouldn't just involve rewriting a bunch of functions.
> It would involve motivating the community to avoid writing that sort of API
> in future, which would take all of us many years to achieve.

I see one of the differences about you and I perceive the API is that
I'm not assuming that every time you see "_new_" in a function there
will be a very exact behavior to be assumed in that function. This
would be nice in theory, but in practice you will see that different
APIs were written by different persons in different years and they
were approved by different reviewers.

I would happy enough if the documentation is correct when stating the
behavior of the function, but I don't pretend that since two functions
both contain the term "new" they can be described by the same notion
of "new". Also this is why we should not create an expectation of what
a function does if it contains "new".

This might work if there was a naming guideline the
contributors/reviewers must commit to, or if a function name is
enforced by the language (e.g. as in the case of C++). Since this is
not the case for FFmpeg, we should not set an expectation about
function terminology and behavior. Same is also true for contexts (we
don't have any "contract" stating that context functions should always
pick a "context" as first argument, and I noted several times even in
OOP languages there are constructs - e.g. static/class methods - which
works as constructors and therefore take no self as argument. In the
case of the C language there is no notion of class, so there is no way
to formally distinguish the two cases. I can come with a more concrete
example if this is not clear enough).

Finally, this does not mean that we should not try to make the FFmpeg
API more consistent (I tried for years), but that does not mean that
we should make a-priori assumptions about how the API behaves when you
read "context" or "new" in a function name - the documentation of the
function should clarify what it does - without resorting to a general
theory setting up too strict expectations which do not match reality.

There are a few examples which should be fixed (e.g. the ugly
swr_alloc_set_opts()) but I don't think we should really
mention/apologize for that in the documentation.

> 
> # Apply this, then iterate
> 
> The argument: OK fine, but dragging down other solutions doesn't help this one.
> We should at least try to solve these problems.
> 
> This is the position I've currently landed up at.  I'm increasingly able to
> justify the big picture decisions behind the document, and we're getting to
> the point where detailed discussions are just putting opinions where evidence
> should go.
> 
> I've talked in a previous e-mail about getting feedback from #ffmpeg and the
> libav-user mailing list.  We've also talked about the value of making the
> document useful to people familiar with other programming languages, so we
> could try reaching out to people who write bindings in other languages.
> 
> This sort of iteration can be pretty quick, because we don't need to wait for
> a major release.  We just need to have something on ffmpeg.org so people know
> this is a "real" project.  As such, I think a "release early, release often"
> approach is the best way forward.

[...]

Andrew, sorry again for the slow reply. Thinking about the whole
discussion, I reckon I probably gave some bad advice, and I totally
understand how this is feeling dragging and burning out, and I'm sorry
for that.

I'm still on the idea of erring on the side of under-communicating for
the reference documentation (with the idea that too much information
is just too much, and would scare people away and make it harder to
maintain the documentation, as now you have to check in many places
when changing/updating it, resulting in contradicting content).

So at the moment I'd be willing to publish an abridged version of your
latest patch, with the suggested cuts - I can make the edit myself if
you prefer like that. This way we can get the non controversial parts
committed, and we can work on the other parts where there is no still
agreement.

Also, I'd like to hear opinions from other developers, although my
impression - from the scattered feedback I read - is that other
developers have the same feeling as me.

In general, having different channels for different targets would be
ideal, e.g. for articles and tutorials. For this it would be ideal to
have a blog entry for the project org, to simplify contributions from
contributors who don't want to setup a blog just for that and to
collect resources in a single place. In practice we lack this so this
is not an option at the moment (and the wiki is not the ideal place
too).