Standardizing DAO proposal formatting

[gregskril]

Since the DAO’s second working group term, most DAO proposals have self-assigned EP (“ENS Proposal”) numbers. This is often done in the title like “[7.1] [Social] SPP3: Marketplace RFP” to use the most recent example.

Common practice is for this is to be [A, B] [Type] Title where A is the term number, B is an appending number of proposals made during that term, Type is “Executable” or “Social” and Title is of course the title itself. In theory that’s good, but it’s often broken in practice:

• Some but not all funding proposals have been broken up like 6.6.1 and 6.6.2.
• Most importantly, duplicate numbers are mistakenly used like [6.47][Executable] Delegation Incentives Program and [6.47] [Social] Election of the New ENS DAO Security Council.
• Spacing between the EP number and the type of proposal is inconsistent. The previous point’s examples are an example of this.

It gets messy because you can’t enforce what people type. So to fix it, I suggest we simplify the title to exclusively contain the actual title. No number and no [Executable] or [Social] tag. The number can be derived after by simply counting the proposals in a given term (easy in code for platforms like the ENS Docs or Anticapture), and the type can be inferred based on where it was published.

The core thesis is: manually tagging each proposal is unnecessary and leads to confusion, so instead of trying to better educate authors we should just remove that responsibility completely.

The proposal process would be:

• When first sharing a draft proposal on the forum, “[Temp Check]” should be prepended to the title followed by a space. So an example title would be “[Temp Check] Do Something Cool”
• When posting a proposal onchain or to Snapshot, the title would simply be "Do Something Cool”. At this point, ideally remove “[Temp Check]” from the forum.
• Offchain platforms would derive the EP number based on {termNumber}.{proposals.length}, and choose how to display the type of proposal as they see fit. The ENS docs would probably keep the current format for simplicity, reconstructing the title to be something like “[EP 1.1] [Social] Do Something Cool”

Does anyone have objections to this, or a better idea on how to stay organized? Tagging people who frequently publish proposals since this is most relevant to you @nick.eth @AvsA @netto.eth @Coltron.eth @kpk.

I acknowledge that its nice to see EP numbers on vote.ensdao.org, and that it’d be ideal for all metadata to be indexable onchain in the case of executable proposals, but if the numbers are wrong (which they often are) then its doing more harm then good.

---

While I’m here, I’d also like to point out semantic markdown formatting. A proposal should only have one H1 followed by H2s, yet many proposals use multiple H1s (here and here for recent examples but there are dozens). This renders weirdly on governance apps, hurts SEO, hurts accessibility, etc. The format should look something like this:

# Title

## Abstract

## Motivation

## Specification

Snapshot offchain proposals have a separate Title field which should be treated as the H1. That means the largest heading should be an H2.

[SpikeWatanabe.eth]

I think that will only complicate matters more, having numbering at least gives some sort of understanding what was going on in between proposals. It was at least convenient to reference proposals if not by directly linking them but by providing number of proposal, if we remove the numbers that will be a total mess.

[gregskril]

Hmm but if I say “According to EP 6.47 …”, which proposal do you think I’m referring to? There are two proposals with that number currently about completely unrelated things. Which gets the URL /dao/proposals/6.47 in the ENS docs?

Or for proposals posted without numbers (since you can’t enforce the author adds it), what do we do? Make it up afterwards is the easy answer. But then the author of the next proposal doesn’t see it and uses the same number! This is what happened with 6.28 (hardcoded version, implied version from it being after 6.27) as another example.

[SpikeWatanabe.eth]

@gregskril

since you can’t enforce the author adds it

moderate the forum properly - it doesn’t have to be forced, but make it so that its clear for everyone in rules that there has to be numbering, and put numbering in proper order from here onwards

[Coltron.eth]

@gregskril

It gets messy because you can’t enforce what people type. So to fix it, I suggest we simplify the title to exclusively contain the actual title.

I like the tags, but this seems like a practical solution.

I imagine the ordering issue might fall forward to offchain platforms then, but if the Official ENS docs are the source of truth that’s easy enough.

@gregskril

This renders weirdly on governance apps, hurts SEO, hurts accessibility, etc. The format should look something like this:

From an SEO standpoint I always assumed the <title> was rendered from the post title field in the Discourse UI, and the main body started with #h1 tags. Therefore, using the first #h1 in the main body for the title was redundant, and starting with #h2 was incomplete.

I’m likely following an old template in my head:

There’s likely a few different ways to solve this. It just comes down to a standard, and whatever works best for how we want to organize things for scraping. If the format I’ve used breaks things, happy to adapt.

---

My pet peeve is out of order #headings and **bold** as a heading instead of emphasis. So of this standard is codified please incorporate that.

[gregskril]

@Coltron.eth

From an SEO standpoint I always assumed the <title> was rendered from the post title field in the Discourse UI, and the main body started with #h1 tags. Therefore, using the first #h1 in the main body for the title was redundant, and starting with #h2 was incomplete.

This is RSS not HTML. If you inspect element on this page, you’ll find that the title “Standardizing DAO proposal formatting” is an H1 tag, implying H2 should be the largest heading in the body.

Weird that the old templates use multiple H1. Not sure how that was created but from my POV it’s semantically wrong. No blame for using it historically! I’ve just had to manually correct enough proposals in the docs recently that inspired me to spin up a thread

@Coltron.eth

My pet peeve is out of order #headings and **bold** as a heading instead of emphasis. So of this standard is codified please incorporate that.

Good additions.

[gregskril]

@SpikeWatanabe.eth

there has to be numbering, and put numbering in proper order from here onwards

Reality is that people try to use the right number but often fail. That’s the whole point of my suggestion to remove it!

@gregskril

if I say “According to EP 6.47 …”, which proposal do you think I’m referring to?

This is the core issue that I think is bad and needs fixing. I don’t think telling people “just do it correctly” is the right fix.

[Coltron.eth]

@gregskril

I’ve just had to manually correct enough proposals in the docs recently that inspired me to spin up a thread

I was going through proposals last night trying to figure out what the heck the different variations were, so I get it and I’m supportive.

[jkm.eth]

I like this a lot. The number and category are actually metadata attributes, and should not be considered part of the title.

For large initiatives it can be helpful to reserve the number in advance, so it can be included in all of the forum discussions, and not risk that number being assigned elsewhere if it turns out a smaller vote on something else needs to be slipped in first. But I think that is something the stewards can manage.

[netto.eth]

Thanks for taking some time to think about this and write.

As much as we try, these mistakes happen, so I’m in support of the idea. We can still show the IDs, integrating and formatting the titles in frontends like Anticapture and Snapshot.