Hi, Since #460498 is merged with #109431, I'm following up to the latter which contains the main discussion.
On Wed, Feb 06, 2008 at 11:30:30PM +0100, Robert Luberda wrote: > Yes, I'm aware of this issue. The doc-base hierarchy doesn't really suit > documentation needs. Please see new hierarchy proposal (still based > on the menu's one) at > http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=37;bug=109431 > I would appreciaty any opinions about this idea. Well that discussion is familiar, indeed. Being one of the originators of the proposal [1], I like it! I like it even after 6.5 years, so I'm consistent if nothing else. :-) I think your proposed mapping is a step forward. However, I will still offer some suggestions. In my view, there are two key ideas: 1. organize by endeavour rather than form, and 2. remove "catch all" sections like "miscellaneous". The first principle is driven by the fact that if I'm writing a GUI application, I'd look for the Qt docs under, say, "gui" rather than "lib". The second principle is similar, actually: I'd look for an Imagemagick app under "graphics" rather than "tools". A huge number of things are "tools", so that has very little organizing power as a section. There are a couple of other principles one could apply: 3. keep the tree balanced, and 4. use the "menu" section when applicable. Item #3 is just to keep the search efficient, while #4 reduces the mental burden: I won't have to map between "Editors" on the menu and "Editing" in doc-base. With these princples in mind, I went through your proposed mappings one by one. After that exercise, I realized that quite a number of my choices are subjective. I can see why someone might make a difference choice than me. I'm starting to wonder whether a more web-like approach where a document could appear in multiple sections might work. Pragmatically, I wouldn't expect a sudden, radical change to be tolerated well. I expect a lot of maintainers would be annoyed and simply ignore the issue if you told them that their doc-base file had to be fixed. Perhaps a gradual approach is best. For example, start with documenting the preferred first- and second-level sections. This addresses the proximal cause of me filing this bug: package apt-dpkg-ref is in section Doc rather than Debian mainly because the documentation for doc-base doesn't describe Section Debian (#153404). In tandem, you might consider trying to fix only the most egregious violators of the preferred sections. In my mind, these are the generics (principle #2): Docs, Doc, Misc, Tools, Utilities, Utils, and Viewers. Unfortunately, these are hard to deal with an automatic mapping since some human has to sit down and figure out the correct section. Perhaps the next step is to audit all these, document preferred categories that will cover each, and file a bug on the offending package. Cheers, -Steve [1] http://lists.debian.org/debian-devel/2001/08/msg01022.html
signature.asc
Description: Digital signature
