CIP-0001 | Section heading specifications #439
Comments
|
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. |
|
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. |
|
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? |
|
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 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 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. |
|
@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. |
@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. |
|
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. |
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. |
|
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 |
|
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. |
|
Closing this so further discussion & editing can continue in #450. |
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-XXXXfollowed 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:
#) title in the formCIP-XXXXfollowed by the CIP title (example...)##), with any subordinate sections having headers of even lower rank.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
MotivationandRationaletags without the definitions afterward (as last mentioned in #437 (review))... mainly because of the cumbersome and uncertain section anchors it creates (as opposed to simple anchors like#motivationand#rationalethat would remain the same even if their definitions are changed).The text was updated successfully, but these errors were encountered: