[FFmpeg-devel] Documentation: proposed changes in the structure

[Jim DeLaHunt]

On  Fri Aug 21 15:35:38 EEST 2020,  Nicolas George wrote:
 > 1. What would you think about putting the documentation for
 >     libavfilter/vf_foobar.c into libavfilter/doc/vf_foobar.texi …
 > 2. What would you think about switching from texinfo to a small basic
 >     subset of HTML for new documentation? …
 > 3. What would you think about using pandoc for processing the
 >     documentation? …
 > 4. What would you think about including the documentation for components
 >     into the libraries? …

I can see the merit of breaking a huge doc file into per-component 
files, especially if they are easier to relate to the corresponding 
source code. I can see that some kind of Markdown might be easier to 
write than Texinfo syntax.

But let me ask a high-level question: what is the goal which these 
changes will serve? How does this the result of this work make the 
FFmpeg project better?

Over on ffmpeg-user, there has been an interesting discussion[1] about 
FFmpeg's documentation, and what improvements people would like to 
see[1][2][3][4]. There are quite a few suggestions[4]. A few  points 
seem worth highlighting here:

1. There is consensus that cross-links are a valuable tool. They help 
achieve both full description and brevity. So, it seems to me that 
excellent cross-link tools are an important feature we should look for 
in any documentation markup language. How does the markup define a link 
target? How does that link target map to a URL? Can that URL stay 
consistent as the surrounding doc changes? How does the markup define a 
link source?  Does the doc compiler handle those links well? Will those 
links stay intact as the surrounding doc changes? Can that link markup 
be derived from doc in C code?

2. There are a number of people volunteering to write documentation. If 
"recruiting more writers" is a goal, how do these changes make that goal 
easier or harder?

3. A number (but not all) of the volunteers identified the git workflow 
as a perceived obstacle.  How do these changes make that crossing that 
obstacle easier or harder?

I don't have strong feelings about this specific proposal. I do think 
that attention to high-level goals for FFmpeg documentation would add a 
lot of value to the project.

Cheers,
      —Jim DeLaHunt

[1] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049718.html

[2] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049668.html

[3] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049702.html

[4] http://ffmpeg.org/pipermail/ffmpeg-user/2020-August/049744.html