[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: 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: