Hello Russ, On Mon 13 May 2019 at 08:40PM -07, Russ Allbery wrote: > That said, just as a matter of style and usability, we should describe the > common case first and make it clear that one doesn't have to open up the > details unless something isn't working right. > > [...] > > The path that, to me, navigates out of that difficulty is to focus on > Policy's role as an instruction manual. Rather than thinking of Policy as > a comprehensive description of one layer of the packaging ecosystem, we > can instead switch (and it is a switch -- this isn't what we've done in > the past) to thinking of Policy as a technical instruction manual for > packagers. And like a good instruction manual, it can document both the > common path for most people, and then have an "advanced usage" section > that digs into the details for special cases or difficult problems. > > The larger problem here, and what I think is a bit of the elephant in the > room, is that doing all of that requires resources, specifically time and > energy to do all the necessary writing and editing. Which we're > chronically short on. I don't think the outlook is so bleak, because I think that something like this can be implemented incrementally. Sections can be gradually rewritten so that the common case is described first, where it's not already, and people writing new sections can have "this is meant to be an instruction manual" in mind as they write. In short, large restructuring does not seem necessary in order to implement what you describe. -- Sean Whitton
Attachment:
signature.asc
Description: PGP signature