RFCs Web Page [mdbook] - Githubissues

polkadot-fellows / RFCs

Proposals for change to standards administered by the Fellowship.

https://polkadot-fellows.github.io/RFCs/

Creative Commons Zero v1.0 Universal

109 stars 47 forks source link

RFCs Web Page [mdbook] #53

Closed mordamax closed 6 months ago

mordamax commented 7 months ago

@PierreBesson suggested rendering our polkadot-fellows/RFCs as a webpage - similar to https://eips.ethereum.org/

Could be made by markdown book https://rust-lang.github.io/mdBook/index.html
Can either integrated into RFC's repo or in https://github.com/paritytech/rfc-book
Do we want to put this page behind subdomain, like https://rfc.polkadot.network?

Tracked in https://github.com/paritytech/eng-automation/issues/1

rzadp commented 7 months ago

I have created the mdbook and I'm looking for feedback.

The book can be previewed here.

Calling thumb-uppers: @xlc @lrazovic @davxy @bkchr

xlc commented 7 months ago

I can't say I enjoy the font and colour scheme (mostly the slime green) but otherwise looks good

shawntabrizi commented 7 months ago

I agree, I don't think there is any need for aggressive styling.

davxy commented 7 months ago

Some personal opinions:

I prefer a simple monospaced font and with less colors around. Something more close to the IETF RFCs (EIP are quite good).
Is possible to auto generate a TOC at the begin for easy navigation? Should be. We can limit TOC depth to maybe 1 or 2 or even 3 (but not 4)
A table like this would be nice for exploration. We also should start think about categories or tags. A good place to add category and tags can be the header https://github.com/polkadot-fellows/RFCs/blob/main/0000-template.md

lrazovic commented 7 months ago

Very well done!

I agree with the feedback provided earlier. I appreciate the concept of a 'Polkadot' theme aligned with the brand identity (https://polkadot.network/ecosystem/brand-hub/), but considering the nature of the site's content, perhaps prioritizing readability in the default theme would be more beneficial. The 'Polkadot' theme could then be offered as an alternative option.

rzadp commented 7 months ago

Thanks for the feedback. :)

Update

I have toned down the Polkadot branded theme.
I'm generating TOCs.
I've separated proposed RFCs into "new", "stale", and the rest
- Currently "new" means PRs created in the last 7 days, and "stale" means PRs not updated for at least 30 days.

Please take another look.

rzadp commented 7 months ago

We also should start think about categories or tags. A good place to add category and tags can be the header https://github.com/polkadot-fellows/RFCs/blob/main/0000-template.md

@davxy The problem with categories/tags in the header is that it cannot be applied for the RFCs that are already merged - the exact hash of the text is on-chain so the text shouldn't be changed after merging.

And even if we're only looking at new RFCs, the problem will be that we won't be able to re-categorize / re-tag them in the future (for the same reason).

How about using github labels for this purpose? Already-merged PRs can be re-labeled.