Russ Allbery:
Niels Thykier <ni...@thykier.net> writes:
Russ Allbery:
Ooo, this is a great framing of the problem. I have a lot of thoughts
about this. Unfortunately, I'm not sure if they're actionable thoughts
since my grand vision requires someone to sit down and do some serious
Policy restructuring and produce a radically different document. But
maybe if I write them all down and enough people feel similarly, it
would be worth doing. I would love to work on this, I am just afraid
that it is the sort of project that I would start and never finish and
thus never accomplish anything of use.
Indeed, it is definitely the thing I would personally prefer to
pre-align on before adventuring on something of this scale myself (were
I in your shoes), so I totally feel your concern about actionability.
I do to some extent want people to encourage me to work on this if they
think it would be awesome, since people being happy with it would be what
would make all the work worthwhile (although I will probably also need
help). :)
Personally, I feel such a change would be for the better. +1 from here.
Interesting choice with the mixing. I was of the understanding that the
idea was one should try to avoid mixing documentation styles according
to Divio. Admittedly, I find it hard to fully stick to exactly one type
of style, so I would be happy if I had just overlooked the "advice on
mixing".
So, I have to admit that I have not read Divio in detail although I have
been pointed at it many times and have had the high-level concepts
explained to me. I've read bits and pieces, but I'm not sure what it says
about mixing.
I think it was my reading of their Introduction section. It says:
"""
Each of them requires a distinct mode of writing. People working with
software need these four different kinds of documentation at different
times, in different circumstances - so software usually needs them all,
and they should all be integrated into your documentation.
And documentation needs to be explicitly structured around them, and
they all must be kept separate and distinct from each other.
"""
Which I interpreted as "don't mix" (particular the "must be kept
separate and distinct"). But re-reading here it might just be that the
policy should use "How to" as a baseline and clearly mark explainer
paragraphs as "Here is the background" as something you can choose to
dive into or easily skip if you are not interested (or have distinct
subsections for how to vs. explainers, which I think you are proposing
in the part that I snipped)
Anyway, as long as you are going into it with open eyes and it seems
like you are!
[...]
As for the content: The "How-to" style would make sense for the target
audience. I am less clear if all of these headlines makes up a "Policy"
as they sounds like something you could find in a "Debian Packaging 101"
guide.
I think that about a quarter of Policy currently is already how-to text.
For example, look at Policy 3.4:
https://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions
This is a disguised how-to document on how to write a good package
description. There's a ton of stuff in Policy like this. What
distinguishes it from a Debian Packaging 101 guide is that the how-to goes
into *way* more depth than a 101 guide: edge cases, exceptions, advanced
bits of packaging, etc.
Sounds good to me. For me it was mostly a question to ensure that
Policy would not end up like "yet another new maintainers guide". You
seem to have a clear vision here for how the Policy would set itself
apart and I think you make a compelling argument.
The main problem from the perspective of helping the typical packager, is
that this is mixed in with oodles of advice that is irrelevant to anyone
except debhelper maintainers. To take another short example, look at the
section on symbolic links:
https://www.debian.org/doc/debian-policy/ch-files.html#symbolic-links
Half of that section is a specification for the packaging helper, which
will fix symbolic links to follow those rules. The rest is sort of a
how-to (mixed in with some basic shell command advice).
Indeed, I am not a fan of the those sections in our Policy!
Side question: Does Policy add anything on the specification for
`symbols` and `shlibs` files as a reference document that is not covered
by dpkg's documentation for these formats? I assume the "symbols guide"
(on /when/ to use symbols and when not too) would go in the previous
section.
Well, one can read the two side-by-side and see, and I'm biased as the
person who wrote it, but I think it does.
Policy duplicates dpkg documentation quite a lot, so this is a question
worth asking, but I do think Policy has a good answer. The value that
Policy adds over the dpkg documentation generally falls into three
categories:
[...]
Again, compelling argumentation for those. I think the rule of thumb is
that for Policy to have a section on something, it would actually have
to be opinionated, provide more examples or follow one of the other
reasons you listed for that section to belong in (this section of) the
Policy.
I agree that this is a source of some duplication of effort, although in
my experience it's not the part that takes the most time. (But I haven't
written triggers or multiarch documentation for Policy yet, so maybe it's
part of the problem.)
Maybe you need to be more opinionated for triggers. "There are -noawait
triggers, they work like this ...! The dpkg tool also support other
trigger types, but you almost never need them. If you do use them, you
are likely to end up breaking the archive, so please don't!" :D
Not sure it would help for Multi-Arch, which is pretty much still at the
stage of:
"""
[...], ma.txt contains the phone number of a friend of mine who
understands Multi-Arch. Just wait through a few minutes of "It's really
pretty simple, just think of package interfaces as ..."; and eventually
you'll learn the rune to put into Multi-Arch field that will fix everything.
"""
(Which is how "regular" people see git: https://xkcd.com/1597/)
What is it you would see go into this section [packaging helper
specification] that is not the previous section?
Literally everything in Policy that you shouldn't think about because the
packaging helpers will cover it. [...]
I suspect this section the package helper specification would be a
reference? Or will it also include explainer parts for "why" we do these
things this way (such as, why are we normalizing symlinks the way we do)?
[...]
Lintian maintainer will love you for breaking all the section numbers
though! :D (I don't have a good solution for that problem).
What I want to do is give sections persistent short codes that are easy to
find and search for somehow and ideally should also serve as HTML anchors.
Maybe we can do something with a Sphinx extension.
Oh, that would have super useful for Lintian indeed. Then you would
also avoid having to keep "dead" sections around just because someone
might have linked via numbering to the following segments.
Sounds like a winner to me if that is possible.
Best regards,
Niels
