On 11.01.2011 09:27, Jonathan Nieder writes: 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. As a current maintainer of doc-base I second this proposal. It would be good to have some discussion about the future of doc-base, its requirements of features it should have, but I don't know if debian-policy is a good place for such kind of discussions. I took the package several years ago when after working on dwww for some time I discovered that the way doc-base is used by maintainers was pretty messy - for example the registered docs often weren't provided, the docs were registered in some random sections, and in general nobody cared about shape of doc-base files. Now I hope the situation is better, but still there's a lot things to improve. One of them is handling of documents translations - this has been a top priority item on my todo list, but still not implemented due to lack of free time. > > 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? There's a similar request in bug#171955, and in general it would be nice to have such thing implemented in both doc-base and frontends like dwww or dhelp. I'm aware that currently is quite hard for maintainer to choose the most appropriate section for the documentation, and that some documents may be suitable for more than one section - for the reasons the categorization would be better solution. > > * 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). It's the package maintainer who is responsible for writing the appropriate Abstract or choosing the documentation to register. I'm affraid the only way to improve quality of the doc-base files is to do some manual reviews of each of them. > > * 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. As I wrote yesterday in #607498, the main point here it's not obvious how frontends should handle such collections. Even adding some file as an Index file wouldn't help much as text files don't support hyperlinks. > > * 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 you wrote `Most abstracts do not make it clear what the document is about.' - how would you add an abstract for automatically registered file? In my opinion, the READMEs should be better handled by the frontends, for example dwww and doc-central already provide links to changelog or README files on theirs own. > > 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. I agree, it would be a good idea to have some team to review the doc-base files, especially that something similar is already done for debconf templates and packages' descriptions. Regards, Robert -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/4d2ce06f.7000...@debian.org
