Re: Debian Documentation Hierarchy
On Sun, Apr 19, 1998 at 11:55:41PM +0200, Christian Schwarz wrote:
>
> The DDH looks great!! Thanks for working on this!
Thanks for the flowers ;)
> 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/)
Well, the packaging-manual states " It does not deal with
the Debian Project policy requirements, [...]", so it is more about
building of a package (it also useful if you build local packages that
don't have to comply with policy, although there is no strong reason not
to). the developers-refernce seems to be the "Glue" between both...
Well, the Debian section is one of the sections that is not fully complete
and ready yet. I'll try to make a list of all available Debian documents and
rethink this particular section.
> - 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!
Yes. Note also that the structure is deep in the Admin and Developer branch,
but it is not very deep (yet ;) in the User branch. I think, the "deepness"
comes from the complexity of the Administration and Developing, and people
that want to to it should be able to face one or two more levels of
ordering. And it is very helpful to find then information. The human brain
has a short time memory for seven or so things at the same time (try it when
going shopping without a list ;). More than 10 items in a section are only
senseful if they are very strong related to each other.
> 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.
YES! I'm glad that you have the same idea as I had. I didn't mention it,
however, because it is part of implementation (front end), and I'm not sure
about the relationship of doc-base and dww and dhelp yet (I'm a bit confused ;)
However, we certainly should make the relationship closer. I already added
some recommendations for the front-end, and I'll add this point. It is not
so easy, though, because the status may change, and at some point it would
be wiser to create a new page or the other way round. Could we have a flag
for this, that I can toggle? For example, sections marked with this flag
would not have any subsections, but indentations (for example). I'll add
such a flag where appropriate until we have another solution.
> - You don't say anything about how different languages of the documents
> are managed. I think this should be explained somewhere, for
> completeness.
The issue is not resolved yet. In the front-end, I prefer the flags
(when in graphic mode) or locales ("DE", "EN") when in text mode,
presented after the document name.
-------------------------
The GIMP (en, de, it)
An ultimative experience for every graphic designer.
-------------------------
In the document hierarchie, I don't know. Please tell me what is the
current status of the discussion?
> - #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.
The point is for me to have some "control" over the appearance of the
Documents and the placement, so that it is consistent with the sections.
The placement is very important, as an incorrect placement will make the
whole thing pointless.
This is the reason why I want total control over sections. I think letting
document registrations create sections will lead to sloppyness and
inconsistency in the long run. If no section is appropriate, it should be
created with the structure of the whole DDH in mind, which would be my task.
It would also allow to move or duplicate some related documents.
> - 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.
Well, slightly changes in the description/definition would be another change
that requires to move some documents. However, you are right, doc-base is
the right way to carry this in the Debian Documentation Project. Well, I
*do* expect a lot of changes in the first few versions, when I'll expend my
examples and try to get the section content more precise. Still some things
are missing, where I didn't found documentation yet (have only a small
subset of packages installed atm). But, this will be limited to unstable
anyway, and I'll sent patches to document-registrations to all affected
maintainers, so the work and unconvenience would be on my side. This will
limit the number of real changes ;)
> 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?
Yes! I hope Adam does agree, too. And I hope he will not get annoyed when I
mess things up ;) No, serious: I expect a very stable DDH ready for 2.1.
I make the following suggestion: I'll try a "dry run", will write
descriptions and definition for the sections, and I'll write document
registrations for as much documentation as I can find in Debian.
Then, probably at the end of March, when Debian 2.0 is finally released,
I'll make DDH fully official and authoritative for all developers, and
have a bunch of document registrations *ready* for a lot of packages
(well, probably without "Abstract:" and the like), that I can send to
the maintainers of the packages. This will also lead to fast
implementation in Debian 2.1!
This does not mean that I want to close development or so. I'll put the
current version in my home directory on master (how can I make it accesible
through http like your policy web pages, Christian?), and will announce it
to get input. It is just that the developers should be prepared that the
DDH can change substantially in the first few weeks.
Does this sound okay, or am I writing stupid things late at night?
> Anyways, this really looks great! I hope that we can get it implemented
> soon!
Yes, but let's not hurry. At the moment, the DDH is usable but not complete.
I can continue working on it (with the input from this list), and the next
step would to agree on a format, so that it can be implemented, too.
I think its highly time to read the Doc Base Manual for me ;)
Thank you,
Marcus
--
"Rhubarb is no Egyptian god." Debian GNU/Linux finger brinkmd@
Marcus Brinkmann http://www.debian.org master.debian.org
Marcus.Brinkmann@ruhr-uni-bochum.de for public PGP Key
http://homepage.ruhr-uni-bochum.de/Marcus.Brinkmann/ PGP Key ID 36E7CD09
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: