Bug#616457: debian-policy: always write version of Debian in documentation at the beginning
On Sun, Apr 03, 2011 at 07:59:10PM -0700, Russ Allbery wrote:
> sergey <sergey_ifeo@rambler.ru> writes:
>
> I do appreciate the problem that you're trying to solve here, but I don't
> think that Policy is the place to do it.
>
> There are a couple of different types of documentation in play, and the
> requirements in terms of stating the applicable version are different.
> For Debian Policy, and for similar documents like the related policy
> documents, the Developer's Reference, the Maintainer's Guide, and the
> getting started guide, the target audience is developers or potential
> developers. Therefore, all of these documents should be assumed to target
> sid. It's not very useful, from a Debian perspective, to have developer
> documentation for older versions, since Debian doesn't update older
> versions except in very specific situations.
Such documents are available as Debian packages, so implicitly the package
provided in lenny should target lenny, etc.
> For user manuals, I can definitely see why it would be nice to clearly
> state in the manual what version of Debian it applies to, so that people
> don't mistakenly try to apply its advice to some version other than what
> it was written for. But I think that adding a Policy requirement to do
> this is overkill. I would guess that the maintainers of those documents
> would be quite happy to add such a note if appropriate (or explain why it
> isn't appropriate) in response to a bug filed against those specific
> packages.
Such documents can get outdated. We need a way for users to notice that.
However since they are generally not packaged, any policy recommendation might
get ignored.
> If you run across a document that's for end-users, that doesn't contain a
> note about what Debian releases it applies to, and where you think such a
> note would be useful, please do file a bug against that package. I think
> that's an entirely appropriate request.
Agreed.
> If the document is on the web and you can't figure out what the
> corresponding Debian package is, well, that's actually another bug --
> documents maintained as a Debian package should probably say that
> somewhere to aid bug filing against the web version. But you can file the
> bug against www.debian.org, noting that you can't tell what package it
> should be filed against, and they can reassign it for you.
>
> I'm marking this bug as wontfix but will leave it open in case other folks
> disagree with my reasoning and would like to argue that Policy should do
> something here.
It appears that a "Debian Documentation Policy" (see <http://www.debian.org/doc/docpolicy>)
exists. I suggest that this report be reassigned to this project if at all possible.
CCing debian-doc@lists.Debian.org for advice.
Cheers,
--
Bill. <ballombe@debian.org>
Imagine a large red swirl here.
Reply to: