[FFmpeg-devel] [RFC] Texi to wiki, and back

Stefano Sabatini stefasab at gmail.com
Sun Nov 11 13:04:49 CET 2012


On date Friday 2012-11-02 17:46:07 +0100, Nicolas George encoded:
> Le duodi 12 brumaire, an CCXXI, Burek Pekaric a écrit :
[...]
> >			They are presented with the nice and intuitive
> > web user interface so they can easily get to the work, without a lot
> > of preparation. Shortly, it is desinged to speed up the
> > documentation building.
> > 
> > If you make it an auto-generated thing, then you will have to decide
> > who has the edit access to the original stuff, which the generated
> > stuff is based on. Also, you have to deal with the merging of
> > auto-generated stuff and user-contributed material, which makes it
> > difficult (but not impossible) to implement and maintain.
> 
> Writing a good documentation takes effort. That is neither new nor
> surprising. A wiki will not magically reduce the amount of work, like you
> seem to believe. It will only change the kind of effort necessary, and the
> nature of the problems if the efforts are not done.
> 
> Writing the documentation ex-cathedra requires time from the developers; if
> the necessary time is not spent, the documentation will be incomplete and/or
> out of date.
> 
> Writing the documentation in an open wiki eliminates that problem but brings
> another one: there is no guarantee of quality. Some wiki contributors will
> make very worthy changes, other will make very pool, inconsistent or just
> plain wrong changes. Maintaining a high level of quality on an open wiki
> requires a huge amount of work from the moderators.
> 
> The idea behind the auto-generated wiki is to try to take the best from both
> worlds: the real documentation is handled by trusted and competent
> developers and discussed on the mailing-list, but the wiki interface allows
> the crowd to submit patches without even realizing they are doing it.

After some research I found this project:
http://code.google.com/p/pandoc/

which converts documents from various formats (with an extensible
architecture).

Possible implementation: we setup an automatic conversion, the wiki is
updated periodically converting the texi docs.

When an user edit the wiki, a patch is generated which is sent to the
ML for review, eventually edited and applied and the wiki is
updated. This would only apply to technical documentation (tools and
libraries) while the current wiki will stand as is (which is IMO just
fine).

The question is, is it possible to setup generic hooks in trac, who
can do that? The other problem is that pandoc may not support trac
wiki and texinfo markup, so this may need to be implemented at the
proper level (pandoc project).
-- 
FFmpeg = Forgiving Furious Mournful Philosofic Easy Gigant


More information about the ffmpeg-devel mailing list