Russ Allbery:
Niels Thykier <ni...@thykier.net> writes:
I had a look at the introduction section of Policy to check who the
target audience is. I cannot find an explicit mention of the target
audience. I suspect there is a conflict here on the content because we
have different audiences in mind for the Policy and the Policy does not
seem to be explicit here.
[...]
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 think that ideally Policy targets all three of your audiences, but not
at the same time, and not with the same priority.
I have a lot of problems with the current structure of Policy, to the
extent that it sometimes interferes with my motivation for working on it,
and one of the big ones is that it doesn't follow any structured design
pattern for documentation, such as Divio [1].
I had Divio in an earlier draft of my email - should have kept it! :D
[...]
I think my ideal structure of Policy would have three major parts.
First, there would be Policy for Debian packagers. This would focus on
the things someone packaging for Debian needs to know, and would be
organized roughly around task. Example sections here would be:
* Choosing an archive area
* Files on the file system (FHS, ownership, permissions, etc.)
* Writing a debian/control file
* Writing a changelog
* Writing a copyright file
* Packaging a shared library
* Packaging a system service
* Using maintainer scripts
In other words, this section would consist primarily of Divio how-to
guides, with some intermixed Divio explanations. (Tutorials I think are
outside the scope of Policy and are better handled elsewhere, such as in
debhelper documentation.)
[...]
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".
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. That is a "risk" (or maybe exactly what you are going for),
which would be fine with me and I would support the idea.
Nevertheless, I feel it has quite some potential to make Policy more
accessible to new contributors and that alone is worth supporting in my
book. Though I am hardly the target audience nor "paying the upkeep
cost", so supporting it is basically gratis for me.
[...]
Second section would be Policy the reference manual for interfaces in the
distribution. Sections here would be:
* Complete list of control fields and their meanings.
* Specifications for the .dsc and .changes files (which packagers mostly
never need to care about, but tool maintainers do).
* The detailed reference documentation on all the ways maintainer scripts
can be called.
* Specification for the symbols and shlibs files.
This is all Divio reference stuff. Whenever we have a comprehensive
explanation of the details of something, it goes here, and then we
liberally link to the reference section from the packaging-focused how-to
section for more details.
Makes sense to me as well. I would indeed also need documentation somewhere.
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.
Finally, there is the reference manual for toolchain maintainers. My
position on this is that it's best-effort documentation and should
probably be a non-normative appendix where toolchain maintainers are
relatively free to just make changes without going through a very formal
process as long as those changes reflect reality. This is, by nature,
going to be incomplete and possibly out of date, but I do think the
project should have *somewhere* outside of any specific package where
people can write down the details of, oh, the other options to
Rules-Requires-Root that we aren't currently using. But we would stick a
lot of disclaimers on it and make it clear that this is internals that
only 10-20 people really need to know about.
What is it you would see go into this section that is not the previous
section? As an example, the `Rules-Requires-Root` case I would have
Policy document the two primary values and that certain tools will
provide their own special-case keywords. But as a tool writer, I am not
sure I would maintain my keywords in Policy.
I don't know if we can get here, but personally I think it would be a
massive improvement over where we are now, even if we spend the next ten
years sorting out structural problems with how we moved things around.
But it's a *ton* of work, so realistically it's never going to happen
unless it excites other people as much as it does me.
I think it would take the Policy editors to have consensus on this as a
direction and then go step by step from there. Maybe turn the current
Policy into "Section II" as starting point and extract stuff into
"Section I" piece by piece.
Lintian maintainer will love you for breaking all the section numbers
though! :D (I don't have a good solution for that problem).
Anyway, that's a very long-winded answer to Niels's question. I think
Policy should primarily have an audience of packagers, including packagers
who need to coordinate cross-package integrations, secondarily have an
audience of tool makers who need a reference manual for Debian's file
formats and integrations, and then have a deprioritized tertiary audience
of toolchain maintainers.
Makes sense.
In that narrative, I think it would make sense for Policy to reference
our primary packaging toolchain a lot more - at least in Section I. As a
toolchain writer, my primary concern here is inertia.
I would prefer that the references enable the tool to evolve over
time. As an example, "This section assumes debhelper-compat (= 13)"
could work because that phrase implies that things can change in a
future compat level.
Probably with some more trade-offs in play than that. Like should
concrete compat levels be listed like I did in my example above? It
would tell people whether it was up to date, but it might not be
feasible for / a good use of Policy editor's time to review everything
with every compat level. Not sure whether that example is truly
applicable, but I think you get the idea.
I think that was the two cents I had on this.
Best regards,
Niels
