Bug#616457: debian-policy: always write version of Debian in documentation at the beginning
sergey <sergey_ifeo@rambler.ru> writes:
> Excuse me for my bad English :-)
> It is like bad tradition now: many documentation do not contain
> information about Debian version. It is very strange for me. How can be
> authors 100% sure that their documentation is absolutely correct for all
> Debian versions, from 1.1 or older to the current?
> Examples - documents with no Debian version:
> http://www.debian.org/doc/manuals/debian-reference/
> http://www.debian.org/doc/manuals/developers-reference/
> http://www.debian.org/doc/manuals/debian-faq/ch-basic_defs.en.html
> http://www.debian.org/doc/manuals/securing-debian-howto/index.en.html
> http://www.debian.org/doc/packaging-manuals/menu.html/
> http://www.debian.org/doc/manuals/intro-i18n/
> Documents where Debian version is not at the begin:
> http://www.debian.org/doc/manuals/maint-guide/ch-start.ru.html
> http://www.debian.org/doc/manuals/debian-java-faq/index.html#contents
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.
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.
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.
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.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: