Re: Debian Packaging Handbook project

[Luca Brivio <lucab83@infinito.it>]

Alle mer 8 agosto 2007, Ben Finney ha scritto:
> Thanks for taking the initiative to do this work.

Thanks for your attention.

> > At this moment, we have the New Maintainers' Guide and a bunch of
> > other more or less good tutorials, anyway when one wants to make an
> > even simple package she/he often have to look at dozens of guides,
> > tutorials, manpages, manuals etc. and not infrequently this will not
> > be enough.
>
> Is the goal to replace those documents, or make them unnecessary for
> the developer to read? Or, rather, is it meant to be an index to the
> documentation that does exist?

The goal is from my POV to produce something much more complete and with a 
different scope: while the NMG etc. are (roughly) tutorials targeted to 
people who want to make their first packages etc., the DPH would be a rich 
manual for all those who maintain packages.

> What I can see being valuable is a document with the clearly stated
> purpose of pointing thhe reader to *other* documents, so that it
> doesn't take on the task of duplicating existing documents.
>
> That way, if someone starts to document some aspect of the procedure,
> it would clearly necessitate the creation of a new document for that,
> or the inclusion of that material into some other existing document.
>
> Without that structure, and a strict policy of being *only* an index
> to existing documents, I don't see how this project would avoid
> creating yet-another-document to read, compounding the problem you
> initially described.

One of the biggest problems we experienced is that the existing documentation, 
albeit useful and rather rich, is not coherent. I think we need something 
more homogeneous, backed by an overall design. This would not be 
yet-another-document to read, instead would substitute many other small 
(often out-of-date or contradictory) documents about major and minor topics. 
The idea is that one might maintain packages without having a lot of 
documents around all the time, just with a big manual which links to other 
documents only for reference. It seems likely that most of this manual 
already exists, and could be put together, edited, expanded and integrated 
with the permissions of its authors, or thanks to its licensing. One of main 
goals is to have a truly organic documentation.

I don't know if such a project deserves to be official, however I wish to try 
to make it work, and see how it might work.

--
Luca Brivio