[FFmpeg-devel] [PATCH] doc: add libavcodec.texi first version

[Stefano Sabatini]

On date Friday 2012-11-02 17:00:10 +0100, Burek Pekaric encoded:
> >>The texi view is suited for developers and the wiki view is suited
> >>for the users.
> >
> >In what aspect is the "wiki view" different from the HTML
> >generated from the
> >texi source files that makes it better suited for users?
> 
> Auto generated wiki defies the purpose of the wiki itself. Have you
> ever used a wiki system so far?
> 
> 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.). 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.

Let me restate that wiki and official docs are not *exclusive*, we can
get the best from both worlds if we specify and separate the *roles*
and *objectives* of the two systems.

The wiki is good for user contributed *high-level* recipes and howtos,
which can be edited with no review and it should not be considered
authoritative for what regards the description of the internal working
of the product. Also it is intrinsically *decoupled* from the product
itself, it is supposed to apply to a relatively recent version of the
codebase, but is not tied to a specific version (you could have a wiki
for each release, but that would be painful to maintain, so I don't
think it should be even considered).

Official docs are integral part of the codebase, and can't be
decoupled on the basis that documentation is not code (which is *not*
true, at least in a very meaningful sense), also it is strictly tied
to the version and history of the project (code and documentation
updates should come together for several good reasons). Also the
documentation of the project internals must go through the review
mechanism, that requires much work but it's the only way to guarantee
(to some extent) an high level of quality / accuracy. Let me also note
that, contrary to what it is usually implied, authoritative
documentation editing is hard work and can take *no less* effort than
coding tasks.

Also official documentation tends to be terse and precise, while an
user-oriented document tends to be more descriptive and tutoring.

It makes sense to keep the two worlds separate, for the same reasons
for which it makes sense to keep separate the microwaves instructions
handbook, which is edited and reviewed by the producer, from the
document describing the recipes that can be performed with the
oven. The "final user" usually has none or scarce interest to document
the instructions booklet, but she may want to extend the list of
recipes, or document workarounds for the known oven issues.

So there is not really a conflict, of course there is some overlap
(FAQ and HOWTOs tend to cover the same target).

Also in general the authoritative documentation contributor is usually
a developer, and she already possesses the expertise and knowledge to
deal with the technical aspects of the review and commit process.
-- 
FFmpeg = Free and Free Murdering Problematic Enlightened Gangster