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