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

[Andrew Sayers]

On Tue, Jul 02, 2024 at 12:16:21AM +0200, Stefano Sabatini wrote:
> On date Sunday 2024-06-16 19:02:51 +0100, Andrew Sayers wrote:
[...]
> 
> 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).

No problem about the delay, although my thinking has moved on a little
(e.g. it turns out GIMP uses the word "context" in a completely different
way than we do[1]).  But rather than argue over today's minutia, here's
a big picture idea...

It sounds like your vision is for smaller, more disparate documentation;
and you're willing to spend some time writing that up.  How would you feel
about taking the AVClass/AVOptions bits from this document, and working them
in to the existing AVClass/AVOptions documentation?  That would require a level
of experience (and commit access) beyond what I can offer, after which we could
come back here and uncontroversially trim that stuff out of this document.

For inspiration, here are some uninformed questions a newbie might ask:

* (reading AVClass) does the struct name mean I have to learn OOP before I can
  use FFmpeg?
* (reading AVOptions) if the options API only works post-init for a subset of
  options, should I just ignore this API and set the variables directly
  whenever I like?

[1] https://developer.gimp.org/api/2.0/libgimp/libgimp-gimpcontext.html