search

paritytech / eng-automation

0 stars 0 forks source link

[EngAut] Aesthetics of Polkadot SDK #10

Open rzadp opened 6 months ago

rzadp commented 6 months 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. I missed this but the links are checked on CI. 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 
### Tasks
- [ ] https://github.com/paritytech/eng-automation/issues/13
kianenigma commented 6 months 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 5 months 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.

rzadp commented 4 months ago

What is the overall prioritization and timeline of this issue? Would be happy to help and get these low hanging fruit parts sorted.

We have included it as part of our OKRs, and I think I can start working on it soon.

rzadp commented 4 months ago

I have proposed https://github.com/paritytech/polkadot-sdk/pull/5154 with a bunch of corrections to the docs.

kianenigma commented 3 months ago

@shawntabrizi has further ideas about about how to do the awesome-list thing, if you get the chance to tackle it :)

Note: https://github.com/paritytech/polkadot-sdk/graphs/traffic shows how big of a traffic our repo has, so I hope it is extra motivation to work on this.

Another side note is the checkmarks in https://github.com/paritytech/polkadot-sdk/community. It seems like even though we have CONTRIBUTING.md in /docs it is not picked up in this list. I am not even sure what is the benefit of following these standards, but it is probably for the best to do it.

rzadp commented 3 months ago

Update:

rzadp commented 3 months ago

Ok, we got CoC and Contributing. For some reason PR template didn't click, I'll look into it.

Screenshot 2024-08-26 at 09 34 34

rzadp commented 3 months ago

A quick follow-up PR: https://github.com/paritytech/polkadot-sdk/pull/5462

lovelaced commented 1 month ago

@kianenigma can you let me know if there are any next steps here or if anything needs doing so I can prioritize accordingly? I know you said it's in a good state but I'd like to understand better what needs to be done in the future.

kianenigma commented 1 month ago

rzadp has done great so far, all the important things related to this are done.

In general, I think the need for someone to "care about similar matters" exists, but I think this is more of a collective/cultural concern, and not something that I can request someone to look into with high priority.

Can be closed.