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.
> If the target audience is package maintainers, then 100% of all debian > contributors should read it. Then we need "simple and easy to > understand" language and examples, because we want *everybody* to > understand this. I agree with Russ that long winded sections of "here > is how you do this manually but really just use debhelper" is directly > counter productive to this audience. > If it is cross-package integration, are we targeting the ones > integrating or the ones providing the integration points? If it is > both, then for more complex topics, it would make sense to split the > topic into two. One for consumer and one for the provider of the > integration, because for the consumer it will probably boil down to > "install path at $X in your deb and run tool $Y" and then the consumer > can skip the provider section as "not relevant". > If the target audience is tool-chain maintainers, then only 5-10 people > need to read the policy and the entire document + related process seems > completely over-engineered. But then, for the same reason, I suspect > this is an unlikely target audience for the Policy. 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. 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]. It may have at one point, but iteratively over the years, and due to some decisions like trying to retain section numbering, we've diverged from that. Even if it were trying to be only one type of documentation, it doesn't consistently stay in that lane. [1] https://documentation.divio.com/ 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.) (This is very rough, this is not the right order, etc. This is just to provide a feel of the nature of this section.) This section would assume that you're using a packaging helper and not tell you how to do things that the packaging helper is going to do for you. There's an awkward line here between describing what to do and being debhelper documentation, but the basic idea is that this would tell you what you are aiming for, and then your packaging helper documentation will tell you where to put configuration files to achieve that. 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. 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. 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. 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. -- Russ Allbery (r...@debian.org) <https://www.eyrie.org/~eagle/>
