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 -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: http://lists.debian.org/20110111082747.gc9...@burratino
