Template for design docs

[brunoapimentel]

This PR aims to stablish a base template from which all design docs will be derived from. Currently, I'm keeping all the commits so the reviewers can go over the changes as the discussion progresses. Before this is changed to "ready to review", all examples will be dropped, and the commits remade.

[a-ovchinnikov]

I like the mostly free-form approach proposed here.

[a-ovchinnikov]

What do you think about moving "Decision" up, right after "Overview"? If the doc is to be used as a quick reference it would be nice to have it closer to the problem statement. Also it looks like not every design requires a decision, "Implement as described here" seems to be implied by the type of the document, maybe it should be marked as [Optional]? Or maybe even made a part of free-form sections when there are several possible strategies? Overall it looks like "Context" will ultimately dictate the structure of everything that follows.

[eskultety]

Also it looks like not every design requires a decision, "Implement as described here" seems to be implied by the type of the document, maybe it should be marked as [Optional]?

Agreed. I would probably go as far as omitting the Decision section completely for now. Remember, we're dealing with design docs for package managers, so the decision inherently is to "implement support for one". We can add it optional in a follow-up patch, we may get clearer picture and overall better feeling of this once we start actively using the template.

[brunoapimentel]

We can mark Decision as optional. I agree it feels very out of place for initial package manage designs.

[taylormadore]

IMO the "Decision" section here should be where we describe what we're going to implement given the "Context" described above. For a design, I would expect it to at a minimum include what is in-scope and out-of-scope.

We might just need a different word to describe it.

[a-ovchinnikov]

Filenames in the draft imply naming scheme with shared counter. This should probably be documented somewhere.

[eskultety]

I'm struggling to justify presence of both Overview and Context. I think having just the former is enough for any necessary background information serving in fact as context for the rest of the document.

[a-ovchinnikov]

"Overview" should serve the same function as an abstract in a paper: to give a brief summary of the main body of text. It is necessary because it provides means to skip or postpone reading of the entire doc. I think naming could be discussed, but having a TL;DR section is important.

[eskultety]

Then it should be called abstract, because I think the definition of abstract is much stricter than that of an overview, what we're doing with these design docs wrt/ pkg manager background is also an overview.
The question still remains, should an abstract be mandatory for the original design docs? I can imagine them being mandatory for the obsolete/update docs, but not for the main document, the title kinda already hints at what it's about --> implemeting new backend.

I can be persuaded otherwise though as I'm a big fan of consistency, so I can see value in having as many fields as possible being mandatory...within reasonable limits, i.e. some fields don't IMO make sense to be mandatory always.

[a-ovchinnikov]

Mandatory fields mean that these fields are applicable to all designs, determining a set of universally applicable ones would require significant effort to analyze all existing designs and distill out all common parts. There is also a big chance of introducing too many unnecessary fields. I've seen mandatory templates with more than half fields ending up being marked as "Non-applicable" which created lots of visual noise and made it easy to miss something important. In some cases it was more productive not to follow the template at all. I don't think it is a good idea to set rules which will not be followed (for whatever reason). I am also concerned with extra maintenance and cognitive load which mandatory fields introduce so would suggest keeping them to a reasonable minimum.

[eskultety]

@a-ovchinnikov I agree with that reasoning so as long as we don't end up with all fields optional and their intent is clearly defined, we're good.

[eskultety]

Description sounds quite vague to me when it comes to designs; Specification sounds more appropriate for the cause (also follows PEP doc nomenclature).

[a-ovchinnikov]

What about "Design"? This is a design doc after all.

[brunoapimentel]

I dropped this section in the following commit. The reason was that I felt it didn't add any value, but added one more level of nesting, which looks horrible IMO (compare the ruby design example in this commit and in the following one).

[eskultety]

Also it looks like not every design requires a decision, "Implement as described here" seems to be implied by the type of the document, maybe it should be marked as [Optional]?

Agreed. I would probably go as far as omitting the Decision section completely for now. Remember, we're dealing with design docs for package managers, so the decision inherently is to "implement support for one". We can add it optional in a follow-up patch, we may get clearer picture and overall better feeling of this once we start actively using the template.

[eskultety]

In your example it is not clear to me what the actual file name should be, IOW the ruby example is named rubygems-001.md, but the actual title is "Initial Design for the Rubygems Package Manager", so we need to provide clear guideline on how the title should correlate with the actual file name in this directory (it's okay if we end up with a different template in a different docs directory serving a different purpose).

[brunoapimentel]

Yes, this was another stab I took to see how it would look like. I will definitely improve and write guidelines for it.

[eskultety]

Apart from the table I mentioned in the ruby example I'm missing a fairly crucial part for the template and those are fields like Updates/Updated by, Obsoletes/Obsoleted by as part of such table which will allow us to directly link related documents in a very visible way. Such fields of course should be marked as optional because you don't have an update doc until you really have one.
Continuining with the thought, we should also provide a guidance in this template on how update/obsolete works, IOW not only we'd link the update/obsolete doc, but if only a portion of the original doc is updated/obsoleted (i.e. not the whole doc), then the relevant sections/subsections should be marked e.g. with [UPDATED/OBSOLETED + link] for better visibility to the reader on which parts they should focus on. Naturally the suggested Last updated date field (recommended in another review comment) would be modified with each such modification to the original document, IOW we'd only permit metadata changes to the original doc, but not contents to keep the doc effectively immutable.

Something along ^^^^these lines should be mentioned in the template guide.

[eskultety]

for a reference, when it comes to the docs header we can get inspired with probably the origins of ADR = RFCs --> https://www.rfc-editor.org/rfc/rfc5143, https://www.rfc-editor.org/rfc/rfc7322 just to name a few tiny examples dealing with format of the RFCs.

Other notable mention: https://www.rfc-editor.org/rfc/rfc7841#section-3

[eskultety]

This is just a summary of the implementation specification and as such is IMO redundant as it provides very little information compared to the specification section.

[brunoapimentel]

I think the summary is really... just a summary. It's a way to help the reader bring to mind all the info that was more thoroughly explained before. It can be optional as well, as I don't see it being useful for smaller docs.

There is also another benefit for this specific section here: clear separation of what's in scope and what's not. But maybe scoping doesn't belong to the design doc.

[eskultety]

There is also another benefit for this specific section here: clear separation of what's in scope and what's not. But maybe scoping doesn't belong to the design doc.

arguably it does, because a given pkg manager is a massive ecosystem with loads of variables and corner cases, so the design doc needs to outline what is being done and what's not, it just needs an appropriate format. I'd refrain from mentioning follow-ups as those IMO don't belong to a formal docs, one's imagination can be very wild when it comes to follow-ups so let the future decide what the follows are going to be. For the rest, an optional summary section would IMO be acceptable, worst case scenario, we'll decide it was wrong and drop it and propose a refined version of the template....RFC did the same...not once

[brunoapimentel]

The follow-ups mentioned here are either things that were mentioned at some point in the design, but were marked as out-of-scope since we want to keep the implementation very basic. They are all features that have been similarly implemented in other package managers.

This is part of the summary, as I see it: "the design touches all these features, this is the subset we want to implement, and this is the subset we don't want to for the first version". Maybe we can just call the section as "out of the initial scope".

[eskultety]

But you never know if any of those follow-ups will ever make it to see the dawn of day, so for a technical doc we really only need to state what we're doing right now. Anything else is good for a presentation, but not for a formal design doc IMO, so please omit any follow-ups and not let anyone get hooked up on the possibility of implementing particular functionality. Then I'd agree that the summary of DOs could be the Decision.

[brunoapimentel]

What do you think about simply stating those as "out of scope"? I did that in the newer commits I pushed.

[brunoapimentel]

I feel like there's a benefit to it... it clearly states, in a summarized form, what the initial deliverable is.

[eskultety]

I think this scoping you have here is actually the decision, because we're purposefully limiting the implementation, so either it stays part of the specification or we move it to the decision (I'm ambivalent on this at the moment based on a single example).

[eskultety]

This whole Ruby ecosystem overview (up to cachi2 impl.) is IMO the actual overview you want to have in this design doc instead of what it currently reads.

[a-ovchinnikov]

Do we want to have back links too? I.e. "Updates: 9999-this-doc-does-not-exist"

[eskultety]

Yes, we do.

[a-ovchinnikov]

s/Overview/Introduction/?

[brunoapimentel]

I proposed the change of this section to Introducion based on what I saw from the RFC examples Erik linked. But looking at it again, I think it is even worse to convey the meaning of TL;DR we are expecting from this section.

But point taken, this is currently inconsistent.

[eskultety]

So, why not Abstract then? Ultimately, I don't care whether it's called Abstract or Introduction, but I think the content should be different, something on the lines of
"Add support for automatic Go toolchain fetching which was introduced in Go 1.21 to address the issue of frequent micro version bumps by some projects using cachi2 to build their software as well as address Go's new 'minimum required version' policy during builds."

[brunoapimentel]

Abstract sounds very adequate, although when I look the word up in online dictionaries, they describe it as a Summary, so that could be another option.

[eskultety]

I think we're converging with this, maybe one more iteration :). Kudos for the inclusion of the Go sample, it's always better to have 2 different docs to compare.

[eskultety]

So, why not Abstract then? Ultimately, I don't care whether it's called Abstract or Introduction, but I think the content should be different, something on the lines of
"Add support for automatic Go toolchain fetching which was introduced in Go 1.21 to address the issue of frequent micro version bumps by some projects using cachi2 to build their software as well as address Go's new 'minimum required version' policy during builds."

[eskultety]

That's because I believe what you currently have in the previous section is the context. For the intro, I think the whole thing needs to be reworded in the sense of why this document even exists which the current intro doesn't do, it just says what Go did in 1.21. It's missing though how this project is impacted requiring some changes this doc will describe.

[eskultety]

This is too free-form. I believe we need to standardize on this H2 heading. Also, I'm still fairly convinced that the paragraphs that follow this heading are the overview of the 1.21 changes that are relevant to the cause, it doesn't say anything about how we're going to solve it - that's good, because that will come later in Proposed solutions!

[eskultety]

I think some standardization is needed also for ^this H2 heading, but I agree the rest of H3+ headings can be left free form and not limit the writer.

[eskultety]

Good use of Decision!

[eskultety]

I know I wrote the content, in retrospec ^this should have somehow been part of References, no need for another section, admittedly I was trying to be unnecessarily formal, just an FYI.

[eskultety]

Similarly here, this should have been part of the broader context sections, or overview or whatever we end up calling it.

[eskultety]

I responded to the Go sample, I don't think this main H2 section should be free-form, its subsections sure can be.

[brunoapimentel]

Let's concentrate this discussion in this thread.

[eskultety]

nitpick: Is the description of the intended content for these sections being purposefully done so that it can be rendered online? I mean, the only thing I expect from a template is to be copy-pasted, renamed, filled out and proposed. So, if we make these description commentaries, people can even keep those comments in their proposed doc and that information won't be rendered, just a bit of thinking out loud.

[eskultety]

I'm not convinced there should be 1+ H2 headings for this, the design should be covered by a single H2 section and N subsections, otherwise we'll break the structure which we're trying to standardize somewhat I think.

[brunoapimentel]

I agree this looks good on the template, as it is more standardized, but having a large document with many subsections forced into a H2 brings a horrible result, at least IMO. As an example, check the Ruby design in this commit, and how I changed it in the following ones. For smaller docs, I believe a single H2 works perfectly.

I am not sure what's the best option here. If nobody minds the excessive nesting (and the hard limit on the H5), then let's just make it a single H2.

(I even considered a separate template for new package manager designs, although I think I still prefer to keep things simple).

[eskultety]

with many subsections forced into a H2 brings a horrible result

We can agree that it's a matter of taste. On the other hand...

If nobody minds the excessive nesting (and the hard limit on the H5)

... if we ever need to go past H5 then I guess we need to rethink whether a given design really needs it, I don't expect that to be a regular thing, but I might be wrong here.