search

cardano-foundation / CIPs

Cardano Improvement Proposals (CIPs)
https://cips.cardano.org/
Creative Commons Attribution 4.0 International
510 stars 319 forks source link

CIP-0001 | Section heading specifications #439

Closed rphair closed 1 year ago

rphair commented 1 year ago

About half of the last few weeks' CIP PRs have come in with the required section headings (Abstract, Motivation, Specification) as H1's (markdown #) instead of the H2's (##) that our planned site generator and current CIP makeover (#389) will apparently require.

Therefore since I often do the first triage for document formatting I've been having to submit the same review each time asking authors to demote the headers: a lot of unnecessary work for authors and/or editors, as in:

Also because the last few CIPs updated in #389 have had an H1 added of CIP-XXXX followed by the CIP title, I'm assuming this is a second requirement. Between these two stipulations, the result would be a proper SEO outline structure which would be easily parseable when the new static site generator is built.

Therefore we should add these two requirements to CIP-0001 in the Structure section:

Perhaps this format nannying shouldn't be necessary: but if it weren't then recent authors would have "gotten the point" and would be submitting CIP PRs with these characteristics already, and by adding it to CIP-0001 we are saving everyone from that nannying process in every affected PR. And we should do something soon before CIP activity gets up to the speed it was in the middle of Q4 2022.

Note @KtorZ I was preparing a PR for this and then reduced it to an issue in the hope this will also be considered along with restoring the former standard of Motivation and Rationale tags without the definitions afterward (as last mentioned in https://github.com/cardano-foundation/CIPs/pull/437#pullrequestreview-1251648728)... mainly because of the cumbersome and uncertain section anchors it creates (as opposed to simple anchors like #motivation and #rationale that would remain the same even if their definitions are changed).

michaelpj commented 1 year ago

I'm fine with the long section headings tbh. Reliable cross-references of any kind are a pain in markdown

My $0.02 on the previous point is that if you want to enforce such an obviously machine-checkable constraint... then get a machine to do it. There's no reason why this repo couldn't have some CI. A CI job that actually tried to build the site would be nice but that rather depends what you end up going with.

KtorZ commented 1 year ago

There's already a CI building the website but it doesn't enforce that specific thing. Reason being that there are at the moment many CIPs that do not abide. So before making it an automatic requirement we must first fix the existing inconsistencies.

Yet I agree with you Robert, it's a bit painful to have to do it over and over... I don't know why, I believe people just copy paste a template from an existing CIPs that is malformed and simply replicate the malformation. So I am not sure that adding those extra bits to CIP 1 will help much for people reading CIPs are likely just using the suggested template which is correctly formatted.

So I am all for enforcing it via CI and even have a friendly bot that makes those suggestions automatically instead of us doing it. But first, we need to normalise what is already there.

GeorgeFlerovsky commented 1 year ago

Sorry for using H1's instead of H2's in CIP-???? (NFT Metadata Oracle).

Honestly, the thought crossed my mind about using H2's, but I didn't see anything about it in CIP-1, so I kept the H1's as-is.

Should we go ahead and fix our headings as you suggest?

rphair commented 1 year ago

Thanks everybody for chiming in. I think @GeorgeFlerovsky makes the point that people would happily produce an SEO outline if CIP-0001 just gave them a tip each about the title & heading level. I believe he's also confirming that a good portion of people are in fact being guided by CIP-0001 (based also on other new submissions).

We could also add such a tip that the longer titles for Rationale and Motivation are literal rather than just an advisement to the author. Sure @michaelpj I think the best way to adjust this would be format correction, but the long standing problems we've had with framework for this suggest it's also useful to standardise this in the authorship itself.

@KtorZ if you are OK with adding concise "tips" to CIP-0001 for either the first point or both, let me know & I will draft a PR for it.

I also thought over the last month the H2 sections Rationale and Motivation could be one-word H2's (creating easy-to-use section anchors #rationale and #motivation for incoming web links), and the extra subtitle texts

Why is this CIP necessary?
How does this CIP achieve its goals?

as headings demoted below H3 (set as H5 above) so as not to conflict with the H3's that follow in the document text. That preserves the simple incoming section links while still reinforcing the section purpose for both readers & authors. But this may be too much format nannying to be done by anything but the CI or web formatter. In the meantime we could simply add it to .github/CIP-TEMPLATE.md. @KtorZ if you also think this "tip" and template modification is OK I will include it.

Also I campaigned a few times for CIP-0001 asking people to put a link to the rendered proposal in the OP for their PR but this also never took hold. It would save us a lot of work, and promote review quality in the time after submission, if we advised authors to do it here (https://github.com/cardano-foundation/CIPs/tree/master/CIP-0001#1a-authors-open-a-pull-request).

Anyway this is potentially 4 "tips" in all now and I think they would give editors peace of mind that we don't have to rush to triage elemental format issues and/or spend time maintaining automation that enforces these requirements.

KtorZ commented 1 year ago

@rphair not sure about the #rationale and #motivation part, as we can already link to both sections in their current form (github provide anchors if you click next to titles):

But I am all in favor of the rest.

rphair commented 1 year ago

the #rationale and #motivation part, as we can already link to both sections in their current form (github provide anchors if you click next to titles)

@KtorZ yes I know, and so will most other GitHub / Git Docs users... the shorter title is a convenience for content creators well outside that sphere. I'm thinking of the many incoming links we should eventually have to both the GitHub and derived CIP web sites from other sources (blog, forum, Wikipedia, presentation slides). One-word anchors will be readily used and will generally work, while multi-word titles are less likely to be used and will be spelled, punctuated and written wrong. I'm thinking of the long term in this case but could leave it for consideration later if you still say so.

KtorZ commented 1 year ago

I think we can handle that directly on the website then; as we can specify shorter anchor there and it'll most probably be the source for non github users.

GeorgeFlerovsky commented 1 year ago

I believe he's also confirming that a good portion of people are in fact being guided by CIP-0001

I may be a special case. I'm very much a "Step 1: Read the manual/spec" type of person. 😄

Others may be more likely to copy an existing CIP they like and then adapt to their needs. CI guidance and an official (up-to-date) template would be helpful.

Actually, the inconsistency in structure of CIPs over time may itself be perpetuating more inconsistency.

When I was structuring our CIP, I almost disregarded CIP-1 when I saw that more recent CIPs diverged significantly from it — it almost seemed like it had gotten stale while informal conventions took over.

The reason why I went back to following CIP-1 was that I saw your recent PRs/discussions about updating it and conforming all the CIPs back to its standard.

rphair commented 1 year ago

cross referencing, to note further discussions of header & title standards:

... to consider these discussions as well when time comes (soon) to submit PR against CIP-0001 where we can begin debating the specifics.

@KtorZ this includes one thing not mentioned in this issue so far... but something which authors will not know unless CIP-0001 tells them (or we have to tell them manually in each PR thread)... that all CIPs, unless Inactive, must have a Path to Active (which currently CIP-0001 currently does not say).

KtorZ commented 1 year ago

Arguably, even Inactive CIPs ought to have a path to active. Because they are usually submitted with "active" as an initial goal. Having said that, I am not sure to get the point you're making here @rphair 🤔 ? do you mean we should emphasis that more in CIP-0001? I don't think we suggest that any section is optional at the moment so I don't see the ambiguity.

rphair commented 1 year ago

@KtorZ: I am not sure to get the point you're making here @rphair 🤔 ?

The point is that the Path to Active semantics are currently only in the section referring to the Proposed status. To indicate that they should apply to all proposals will take a bit of rewriting.

rphair commented 1 year ago

Closing this so further discussion & editing can continue in #450.