Re: why hide the docs?

|--==> tim hall writes:

  th> 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.

  th> 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

  th> OK, Please post any information you find up here. I'm severely 
time-limited 
  th> right now, so even a link to the Policy document will speed things up. 

http://www.debian.org/doc/debian-policy/ch-docs.html

  th> Is it 
  th> worth getting to grips with docbook or similar?

I  don't   know,   but I  think  docbook   is  a  good  candidate  for
documentation code.

  >>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)

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

Yes, and also  make sure that  packages are working properly, they get
updated when the upstream author releases a new version, fix bugs etc.

I just mentioned the doc issue here, but there's *lots* to do..

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

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

Well, the policy it's a  pre-condition. All Debian maintainers have to
respect the policy, and if they don't at least you have arguments.

The policy it's a really important document.

  >>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>.

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

That's a good idea, not too difficult to implement. I'll do that.

  th> I'm happy to keep working on the FAQ that is up on Alioth currently, I'm 
doing 
  th> a batch of installs at the moment, so it's something I can work on while 
I'm 
  th> busy. I could do with some direction from the list here. I feel that the 
FAQ 
  th> could have an install guide pulled out of it and reduce the FAQ to actual 
  th> questions.

Yes that's what I was trying to do.  Installation info shall all be in
the Install section of the left-side navigation bar.

  th> That said, if anyone has ideas to add, please don't hold back, we 
  th> can always rationalise later.

Right.

Cheers,

Free