[FFmpeg-devel] [PATCH] doc: add libavcodec.texi first version
nicolas.george at normalesup.org
Fri Nov 2 17:46:07 CET 2012
Le duodi 12 brumaire, an CCXXI, Burek Pekaric a écrit :
> Auto generated wiki defies the purpose of the wiki itself. Have you
> ever used a wiki system so far?
I have used a wiki system already, thank you very much.
> The wiki system is designed for user contributions (for example
> Wikipedia is a wiki system, too). It is provided as a convenient way
> for people to contribute to a project (in our case the
> documentation), adding/updating articles and building a knowledge
> base for future reference. That makes it easy for a project to build
> the documentation quicker, since a lot of people can contribute to
> it, without even knowing much about coding (or texi, git, patches,
> mailing lists, etc.).
Yes, that is exactly true. What you omit to mention is how it makes easy for
users to add spam, or just wrong and bad information.
> 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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 198 bytes
Desc: Digital signature
More information about the ffmpeg-devel