doc-base revisited
Hi,
Since 2005 (452a1383), policy has recommended registering
documentation with doc-base. I'd like to revisit that recommendation,
see how well it is working, and discuss whether we can make it better.
Aron Xu wrote[1]:
> To be honest, I don't see the necessity to register those fcitx
> documentations to doc-base, resons:
>
> 1. Users and developers who are interested in fcitx are required to
> have an X11 environment (fcitx is a X input toy). If so, I think
> nearly all of them will find the documentations themselves and open
> them with a browser (or text editor) to view them (see 2 for reason).
>
> 2. Registering to doc-base won't benefit users of Yelp or something in
> same category.
>
> 3. Documentations about how to use doc-base is not so good, or we
> won't be dealing with this problem now.
>
> 4. The reason why I register them is to make lintian calm.
I also can say that as a user, I often have a better experience
browsing in /usr/share/doc by hand than using dwww. Why is that?
* The registered documentation is very sparse. It is not obvious
where any given kind of information is to be found (the categories are
especially unhelpful and I suspect something more faceted like debtags
might do a little better). Maybe it would be better to avoid
categorization altogether and make sure that the search features of
documentation browsers work well?
* Most abstracts do not make it clear what the document is about.
* The same document is registered multiple times. I used to
find it especially annoying to find prerendered text versions of
manual pages listed alongside "chapter book" manuals (dwww and similar
tools are capable of translating manual pages themselves, so the
additional rendered versions seem redundant).
* There is no clear separation between user-oriented documentation
(manuals) and developer-oriented documentation (design documents).
As a packager my complaints are fewer, and I am happy with the
opportunity doc-base registration provides to get to know the
documentation I am providing.
* The doc-base specification is a bit cryptic. It is especially
unclear what one is supposed to do with collections of text documents.
* Registration can be a bit tedious. I assume most READMEs do
not need to be registered, but why? Maybe they should be registered
automatically?
As an idealistic solution, I would like to proposed the following:
* Leave doc-base policy basically the same as today (though I'd be
happy to work on making it clearer with respect to details like text
file handling).
* Treat some mailing list (debian-doc?) as the (unofficial?)
maintainer of doc-base registration files in all packages. Whenever a
package gets new documentation, registrations would be proposed to
that list. Maybe there could be a pseudo-package so bugs in doc-base
registration would go directly to that list. This way there would be
some consistency and editorial control attached to the entire index of
documentation.
Does this sounds sane? Would anyone like to help make it a reality
(maybe this would make sense as a new announced service or as a DEP)?
Jonathan
[1] http://bugs.debian.org/607498
Reply to: