[RFC] Documentation of videolan

[Alexis de Lattre]

These are my ideas on how the documentation of videolan should evolve in
the coming months. I would like to have your comments on my ideas.

First, the problems with the actual documentation :

- we only build it in HTML,

- there are redundancies between the 4 user documentations
(Introduction, explaination on how to install the softs and a satellite
card for example...)

- some documentations are out of date...


My idea is to transform all the documentations in DocBook format and
segment the sections in separate files so that we can include the files
in more that one documentation.


For example, the description of the installation of vlc could be in one
Docbook file and included in :

- VideoLAN Quickstart

- VideoLAN HOWTO

and used to generate :

- the text file "INSTALL" in the CVS and tarballs


Another example is the FAQ for vlc (same for vls) which could in included in :

- VLC HOWTO

- the text file "FAQ" in the CVS and tarballs

- a separate HTML page on the Web site.


My other idea is for the options of the command line of vlc and their
description. It could be in Docbook format and then transformed in other
formats so that it could be included in :

- vlc --help (I don't have a precise idea on how to to that)

- man vlc (with the docbook-to-man package, not tested)

- VLC HOWTO

Concerning the explaination of the global videolan solution, I think we
should put everything concerning the VLAN solution in a separate page
with separte documentation, and not include it in the VideoLAN HOWTO,
because it gives the impression that VideoLAN is a very complex solution.
It could be a page http://www.videolan.org/network/vlan/ with links
to a specific doc and a download page with VLAN server, VLAN bridge,
mini-VLANserver, etc...

Then we will have to setup the Web site so that the docs are
automatically built in HTML, PS and PDF (we can do that easily on the
server now that it is in Debian Woody...) every time there is a new
commit concerning the documentation.

The problem with this solution is that we will need the 3 branchs and
the CVS (vlc, network, vls) to build the user documentations. This
shouldn't be a problem for the Website, but a little bit more complex
for the guys who want to build it themselves.

I am waiting for your comments and ideas...

-- 
Alexis
-- 
This is the vls-devel mailing-list, see http://www.videolan.org/vls-devel/
To unsubscribe, please read http://www.videolan.org/lists.html
If you are in trouble, please contact <postmaster at videolan.org>