search

paritytech / eng-automation

0 stars 0 forks source link

[Draft] [EngAut] Aesthetics of Polkadot SDK #10

Open rzadp opened 1 month ago

rzadp commented 1 month ago

An initiative to improve the aesthetics of Polkadot SDK.

Initial writeup - https://hackmd.io/dK0y-MHCQDKiroJFsvKhGg

Kian:

In much the same way that "Das Auge isst mit" ("the eye eats with") emphasizes the importance of visual appeal in food, programmers also care deeply about the aesthetics of the SDKs they work with.

Polkadot-sdk, despite being one of the most active codebases in the entire web3 space, has somewhat mediocre aesthetics. As one mere example, I updated our README for the first time since moving to the mono-repo, and it is still lacking a lot of basics.

  • The type of work needed to fix this is unfortunately deemed boring, yet I argue that it is as important and should be valued. It requires little engineering knowledge, yet it requires:
  • A deep sense of care for tidiness. Having mild OCD is a bonus. Knowing what are the best practices and programmers want to see enough understanding of the polkadot+sdk to distinguish correct and incorrect descriptions and setups

Base deliverables

Current state Desired state
There are crates with a very lousy readmes/descriptions. At least 1-2 full sentences and/or a link to a broader context in every published crate.
There are links to substrate.io all over. All links to substrate.io removed/replaced.
No link checker, some links are expired. Links are checked on CI.
There is no instructions / scripts for installing prerequisites of polkadot-sdk. A script should exists, and be tested on CI. On a fresh Ubuntu, it should be possible to build polkadot-sdk after running this script.
There is no instructions / scripts for installing prerequisites in the templates. We should link to the script above, and it should be CI tested too. See this.
The template readmes did not receive any love for some time. All 3 templates have shiny new readmes, dockerfiles, are built on CI. See this - work already started

Stretch deliverables

Current state Desired state
The docs have an ugly domain: https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/index.html Provide a better domain.
The templates do have a CI to make sure they build, but the CI does not check that all instructions in the README (such as running a local dev chain) are working correctly. A CI makes sure that basic, common instructions for running a local chain are working, and blocks are produced.
Awesome links are spread across Awesome Substrate and Awesome DOT Awesome links consolidated into awesome-polkadot-sdk
kianenigma commented 1 month ago

At least 1-2 full sentences and/or a link to a broader context in every published crate.

Truthfully it is very hard to fix this. Maybe we should use AI here, give it each crate, and ask it for a 1 sentence explanation.

kianenigma commented 1 week ago

There are crates with a very lousy readmes/descriptions.

About this, we have 90/10 situation: 90% of the issue can be solved with 10% effort. We mainly need to focus on the handful of crates that have the most visibility. To start, the top 3 IMO are:

  1. polkadot-sdk
  2. polkadot-sdk-frame
  3. frame-support

For these, we should provide good READMEs. Easy thing is to point to get pages of polkadot-sdk-docs (hopefully with a new domain, or the old one).

I'd say the above few are important. What is the overall prioritization and timeline of this issue? Would be happy to help and get these low hanging fruit parts sorted.

There is no instructions / scripts for installing prerequisites of polkadot-sdk.

Is being solved in PRs linked to https://github.com/paritytech/polkadot-sdk/issues/4650#issuecomment-2180787562.

The template readmes did not receive any love for some time.

Is also partially solved thanks to you :) needs more love tho.