Re: Debian Documentation Hierarchy
The DDH looks great!! Thanks for working on this!
Here are a few comments (unsorted):
- The packaging-manual and devref are listed in section
debian/devel/maint, while the policy manual is listed in
debian/devel/maint/policy. This is suboptimal, since all three manuals
are part of the `policy'. (I'd suggest to move all manuals into
policy/)
- The structure seemed a bit deep when I had a look at it for the first
time. But then, when I checked out the examples, I noticed that you
don't just want to register documents there, but also some general
notes as how-to-report-a-bug, which is a great idea, IMO!
With that, I'm thinking of the following: Wouldn'd it be good to
suggest that our online menu systems don't create a new menu page for
each section of level 3 or below? For example, the entries in
instadm/hardware/hd could probably all be listed on a single page.
- You don't say anything about how different languages of the documents
are managed. I think this should be explained somewhere, for
completeness.
- #5 of the Guidelines duplicates a lot of aspects which would better be
part of the Doc Policy Manual. I'd suggest that you leave these things
out and refer to this manual (to be created) instead.
- You asked in which package the guidelines and the DDH should be
shipped. I think that the doc-base package would be the right place.
Note, that once the structure is set up, you can't make large changes
too often, since all other packages would have to be updated. The only
changes I expect are new sections or splitted sections--and such
changes don't have to be available immediately since only a few
packages will be affected.
I'd suggest that you set up a web page where maintainers can look up
the current (authoritative) version of the DDH. From time to time, you
could tell the doc-base maintainer (via mail or by a bug report) to
update the package (but this doesn't have to be done too often I
think). Do you think this would be a working solution?
Anyways, this really looks great! I hope that we can get it implemented
soon!
Thanks,
Chris
-- _,, Christian Schwarz
/ o \__ schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
! ___; schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
\ /
\\\______/ ! PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
\ / http://fatman.mathematik.tu-muenchen.de/~schwarz/
-.-.,---,-,-..---,-,-.,----.-.-
"DIE ENTE BLEIBT DRAUSSEN!"
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: