Re: why hide the docs?

Last Monday 29 November 2004 09:55, Free Ekanayaka was like:
> |--==> tim hall writes:
>
>   th> Last Thursday 25 November 2004 19:23, Damien Cirotteau was like:
>   >>Any volonteer to manage such a project?
>
>   th> I'd love to, but seriously don't have time at the moment. Could we
> create a th> page or two on alioth to work stuff up?
>
> Dear all,
>
> the documentation issue  is a  rather  important one, and at  the same
> time is one of the hardest as it primary needs wide collaboration.

Agreed.

> This a wide topic. My medium/long term wishes would be:
>
> 1) Carefully examine what the Debian policy says about documentation,
>    find its current drawbacks and figure out what shall be done to
>    improve the situation

OK, Please post any information you find up here. I'm severely time-limited 
right now, so even a link to the Policy document will speed things up. Is it 
worth getting to grips with docbook or similar?

> 2) Create an official Debian subproject [0] called Debian Multimedia [1],
>    which shall deal with the quality of audio/multimedia applications in
>    Debian, and in particular takes care that packages are well documented,
>    with respect to 1)

And also includes menu structure, icons and other stuff covered by Debian 
Policy.

> Well, this would be the ideal world, and we all know about it..

The above covers policy-level decision making, but doesn't necessarily ensure 
that the work gets done. (OK, the word /ensure/ is a little hopeful here ;-)

> In the real, hic et nunc, world I'd suggest to create a new demudi-doc
> package in the Alioth repository [2].
>
> We could  use such package as a  temporary workaround to  supply extra
> documentation, whenever Debian  lacks it,  and   to make  the  already
> available documentation (typically in /usr/share/doc/<package>) easier
> to access.
>
> A rough  idea which comes to  my mind right  now is to have demudi-doc
> automatically  create  an html  index  with the  same structure as the
> application menu and whose entries point to /usr/share/doc/<package>.

Yes, it is vital that we all work to the same menu structure - I find it's a 
really good way of breaking down the overview into manageable chunks.
It would be useful if the Alioth pages could contain a table of Packages / 
Document formats and a column or two where we can grade the quality, extent 
and completeness of docs. The most time consuming part of the operation seems 
to be figuring out where the blanks are.

I'm happy to keep working on the FAQ that is up on Alioth currently, I'm doing 
a batch of installs at the moment, so it's something I can work on while I'm 
busy. I could do with some direction from the list here. I feel that the FAQ 
could have an install guide pulled out of it and reduce the FAQ to actual 
questions. That said, if anyone has ideas to add, please don't hold back, we 
can always rationalise later.

cheers

tim hall
http://glastonburymusic.org.uk