Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Template for design docs #601

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Template for design docs #601

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
46e89a8
WIP: Initial attempt of a template, plus adapting Ruby design to it
brunoapimentel Aug 15, 2024
eea2b4d
WIP: Getting rid of the Description section
brunoapimentel Aug 15, 2024
ac37672
WIP: Improve the template and adapt the Ruby design to match it
brunoapimentel Aug 20, 2024
6d8d4a9
WIP: Added the Go 1.21 toolchains design as an example
brunoapimentel Aug 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/designs/0000-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Title

Updated by: [0000-this-doc-does-not-exist]()
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we do.


Obsoleted by: [0000-this-doc-does-not-exist]()

*(these sections should only be added when necessary, and should always include the links to the relevant documents)*

## Introduction

This section should bring a short summary of what this document is covering, the main points it is going to describe, and why it is important. Ideally should be kept under two paragraphs.

## Context [optional]

Explains the context outside the mere technical aspects of the design that existed when it was written. It must make clear what other influences where at play that affected the decisions that were taken. In case there is nothing relevant to mention about the context, this section can be skipped.

## [Free-form sections]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's concentrate this discussion in this thread.


The actual content of the design should be placed under one or more sections that can be named freely. Note that they should be level 2 headings (H2), but each section can also be subdivided by nested headings (H3, H4, H5 or H6) if needed. Only a single level 1 heading (H1) should exist, and it is strictly reserved for the title.
Comment on lines +18 to +19
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


## Decision/Outcome [pick one]

Document here what decision was made, or what outcome is expected out of the design that was created. In case several options were presented in the design, this section must clearly state which one was chosen and the reasons for it. In case of a new package manager design, or a completely new feature to an existing package manager, this section can only include a brief summary of what the implementation will cover, since it is implied that the decision.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Loading