From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id 58B4C4B220 for ; Mon, 1 Jul 2024 22:16:35 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 55A8368D5EE; Tue, 2 Jul 2024 01:16:32 +0300 (EEST) Received: from mail-ej1-f53.google.com (mail-ej1-f53.google.com [209.85.218.53]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 9622C68D5EE for ; Tue, 2 Jul 2024 01:16:25 +0300 (EEST) Received: by mail-ej1-f53.google.com with SMTP id a640c23a62f3a-a72988749f0so528024266b.0 for ; Mon, 01 Jul 2024 15:16:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1719872184; x=1720476984; darn=ffmpeg.org; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:to:from:date:from:to:cc:subject :date:message-id:reply-to; bh=n2l7ieglRllBwydotE5/n8O+/r+6XE7dhiC/y8zjTRk=; b=MG+E+WtVjJ1NzFOy0G2AdrVU/pnBCQcRbvtkcfoVBkyRdsvQil0Ql84VaaTnqiBF9T +c9Oaf1xaBzadZ/AB8/fNjN5ZgQIYgML4gvlB4nxY+NN130uipx5RPVEMbJlsdQamIn6 LkanSWjtNmIMyoP+4aLUzzhCvBQsIrBpKahssYH+08TPSxSd7wElLE68BdVR9WDBPpQk KM/4HvlAM65PIX3ZpGlitY9Q8DAuNvpHpBj+4JO/1KEXfwRPBKF6ZUUD3dvE/uq9fFu8 t3uwzj4Q9030xri4KaSS0e2VG8IKW9vf1K8+lvN7f2PMotNeZ2WjeIEoJtQb9iZKQMA2 c9Rw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1719872184; x=1720476984; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:to:from:date:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=n2l7ieglRllBwydotE5/n8O+/r+6XE7dhiC/y8zjTRk=; b=qnQfa0miFOhlj4SnO3UuYlN2QLCciePkr0ludLVCvnpcewGpR4LS14p5JUFge3ZQq/ xA1BHd3IPuIQVuvbd+8POpPPybhRewiWZlz+/MbNKZHrji7C8Gc9i/l7TIhN4OraeNtS H1lQJOzx+Iy4SjsFuHJexc8g8YEB1d/kYWYkCgwhRFG+gCyusuApTzoKhZbvy7fj1tQL Pnzp7yssMZxKtrDg5fRLna3FwlSX4nbXkGS9NDzv16kpYVgHHXbVsZXr9GxZ2ND9lfzl F221qbmVE+5M27nLNf87E0BgUic3s4IZMZvNf69PslHvoEh1kUZiGlGb2cSKf4r89vDL SNUw== X-Gm-Message-State: AOJu0YysEp5WBeQGyKgI9sZ7eGFXa4od/Cd3QJ9MGM2CMv0F4aN9K9i8 vhc+neT5+jOcOL6clXDI8BB4YtYmNbjfXH00GeYz7HocUt4mzIN/MUiobKBs9ZM= X-Google-Smtp-Source: AGHT+IEiyggjU/soWSlrzZmZVw55iRUj5jNNqkFHrU7GKS0RxKEy3hJ0+xW3gcr303jonWb0AIUQuw== X-Received: by 2002:a17:906:a19a:b0:a72:450f:6045 with SMTP id a640c23a62f3a-a751447b0demr427319766b.21.1719872183474; Mon, 01 Jul 2024 15:16:23 -0700 (PDT) Received: from mariano (dynamic-adsl-84-220-189-10.clienti.tiscali.it. [84.220.189.10]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a72ab08f74dsm364698566b.169.2024.07.01.15.16.23 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 01 Jul 2024 15:16:23 -0700 (PDT) Received: by mariano (Postfix, from userid 1000) id 0BF60BFCE8; Tue, 2 Jul 2024 00:16:21 +0200 (CEST) Date: Tue, 2 Jul 2024 00:16:21 +0200 From: Stefano Sabatini To: FFmpeg development discussions and patches Message-ID: Mail-Followup-To: FFmpeg development discussions and patches References: <20240418150614.3952107-1-ffmpeg-devel@pileofstuff.org> <20240604144919.213799-1-ffmpeg-devel@pileofstuff.org> <20240604144919.213799-2-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: User-Agent: Mutt/2.1.4 (2021-12-11) Subject: Re: [FFmpeg-devel] Development process for explaining contexts (was Re: [PATCH v6 1/4] doc: Explain what "context" means) X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: 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). _______________________________________________ ffmpeg-devel mailing list ffmpeg-devel@ffmpeg.org https://ffmpeg.org/mailman/listinfo/ffmpeg-devel To unsubscribe, visit link above, or email ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".