Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[EngAut] Aesthetics of Polkadot SDK #10

Open
1 task done
rzadp opened this issue Jun 3, 2024 · 10 comments
Open
1 task done

[EngAut] Aesthetics of Polkadot SDK #10

rzadp opened this issue Jun 3, 2024 · 10 comments

Comments

@rzadp
Copy link

rzadp commented Jun 3, 2024 •
edited by mordamax
Loading

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
Preview Give feedback
  1. Add a ribbon to substrate-website #13
    mordamax
@kianenigma
Copy link

kianenigma commented Jun 5, 2024 •
edited
Loading

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 kianenigma mentioned this issue Jun 12, 2024
Closed
@kianenigma
Copy link

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 paritytech/polkadot-sdk#4650 (comment).

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

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

@rzadp
Copy link
Author

rzadp commented Jul 17, 2024

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.

@kianenigma kianenigma mentioned this issue Jul 23, 2024
Merged
@rzadp rzadp mentioned this issue Jul 26, 2024
Merged
@rzadp
Copy link
Author

rzadp commented Jul 26, 2024

I have proposed paritytech/polkadot-sdk#5154 with a bunch of corrections to the docs.

github-merge-queue bot pushed a commit to paritytech/polkadot-sdk that referenced this issue Jul 26, 2024
@kianenigma
Replace homepage in all TOML files (#5118)
d3d1542 
A bit of a controversial move, but a good preparation for even further
reducing the traffic on outdated content of `substrate.io`. Current
status:

<img width="728" alt="Screenshot 2024-07-15 at 11 32 48"
src="https://github.com/user-attachments/assets/df33b164-0ce7-4ac4-bc97-a64485f12571">

Previously, I was in favor of changing the domain of the rust-docs to
something like `polkadot-sdk.parity.io` or similar, but I think the
current format is pretty standard and has a higher chance of staying put
over the course of time:

`<org-name>.github.io/<repo-name>` ->
`https://paritytech.github.io/polkadot-sdk/`

part of paritytech/eng-automation#10
github-merge-queue bot pushed a commit to paritytech/polkadot-sdk that referenced this issue Jul 29, 2024
@rzadp
Various corrections in the documentation (#5154)
de73c77 
An attempt to improve [the
docs](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/index.html)
by applying various corrections:

- grammar/stylistics,
- formatting,
- broken links,
- broken markdown table,
- outdated vscode setting name,
- typos,
- consistency,
- etc.

Part of paritytech/eng-automation#10
@rzadp rzadp mentioned this issue Jul 29, 2024
Merged
TarekkMA pushed a commit to moonbeam-foundation/polkadot-sdk that referenced this issue Aug 2, 2024
@kianenigma @TarekkMA
Replace homepage in all TOML files (paritytech#5118)
ff5ec0d 
A bit of a controversial move, but a good preparation for even further
reducing the traffic on outdated content of `substrate.io`. Current
status:

<img width="728" alt="Screenshot 2024-07-15 at 11 32 48"
src="https://github.com/user-attachments/assets/df33b164-0ce7-4ac4-bc97-a64485f12571">

Previously, I was in favor of changing the domain of the rust-docs to
something like `polkadot-sdk.parity.io` or similar, but I think the
current format is pretty standard and has a higher chance of staying put
over the course of time:

`<org-name>.github.io/<repo-name>` ->
`https://paritytech.github.io/polkadot-sdk/`

part of paritytech/eng-automation#10
TarekkMA pushed a commit to moonbeam-foundation/polkadot-sdk that referenced this issue Aug 2, 2024
@rzadp @TarekkMA
Various corrections in the documentation (paritytech#5154)
f104abc 
An attempt to improve [the
docs](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/index.html)
by applying various corrections:

- grammar/stylistics,
- formatting,
- broken links,
- broken markdown table,
- outdated vscode setting name,
- typos,
- consistency,
- etc.

Part of paritytech/eng-automation#10
@mordamax mordamax changed the title [Draft] [EngAut] Aesthetics of Polkadot SDK [EngAut] Aesthetics of Polkadot SDK Aug 2, 2024
@rzadp rzadp mentioned this issue Aug 5, 2024
Merged
@kianenigma
Copy link

kianenigma commented Aug 13, 2024 •
edited
Loading

@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.

github-merge-queue bot pushed a commit to paritytech/polkadot-sdk that referenced this issue Aug 15, 2024
@rzadp
Update links in the documentation (#5175)
a71fdce 
- Where applicable, use a regular [`reference`] instead of
`../../../reference/index.html`.
- Typos.
- Update a link to `polkadot-evm` which has moved out of the monorepo.
- ~~The link specification for `chain_spec_builder` is invalid~~
(actually it was valid) - it works fine without it.

Part of paritytech/eng-automation#10
github-merge-queue bot pushed a commit to paritytech/polkadot-sdk that referenced this issue Aug 15, 2024
@rzadp
Update links in the documentation (#5175)
b5029eb 
- Where applicable, use a regular [`reference`] instead of
`../../../reference/index.html`.
- Typos.
- Update a link to `polkadot-evm` which has moved out of the monorepo.
- ~~The link specification for `chain_spec_builder` is invalid~~
(actually it was valid) - it works fine without it.

Part of paritytech/eng-automation#10
github-merge-queue bot pushed a commit to paritytech/polkadot-sdk that referenced this issue Aug 23, 2024
@rzadp
Improve the appearance of crates on crates.io (#5243)
c66f7bd 
## Context

Currently, many crates have no readme files, even though they are public
and available on crates.io.
Others have just a couple of words that does not look super presentable.

Even though probably nobody starts a journey with `polkadot-sdk` or its
documentation with a readme of a random low-level crate, I think it
would look more mature to have a little better readmes there.

So, in an attempt to improve [the
aesthetics](paritytech/eng-automation#10) of
`polkadot-sdk`, I propose a set of consistent, branded, better-looking
readmes for all published crates.

## What's inside

- ~~New readme files for published crates.~~
- A python script to generate new readmes, for the crates that have
none.
  - It will skip crates that do have a readme, and private crates.
- Added a new image asset to the repo - logo with a background.
- The main readme of the repo uses a [nice
trick](https://github.com/paritytech/polkadot-sdk/blob/ce6938ae92b77b54aa367e6d367a4d490dede7c4/README.md?plain=1#L4-L5)
to accompany both light and dark modes - but that doesn't work on
`crates.io` so a single logo with a background is needed.

## Example

### Current

![Screenshot 2024-08-04 at 16 13
36](https://github.com/user-attachments/assets/3ae0881d-0f40-4614-9d2c-3c95029f0820)

### Changed

![Screenshot 2024-08-04 at 16 12
28](https://github.com/user-attachments/assets/fa7eadc8-aec8-4f77-84d9-54d63ce189cd)
@rzadp rzadp mentioned this issue Aug 23, 2024
Merged
@rzadp
Copy link
Author

rzadp commented Aug 23, 2024

Update:

github-merge-queue bot pushed a commit to paritytech/polkadot-sdk that referenced this issue Aug 25, 2024
@rzadp
Add symlinks for code of conduct and contribution guidelines (#5447)
91b5a49 
Addresses
[this](paritytech/eng-automation#10 (comment)).

> 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
Copy link
Author

rzadp commented Aug 26, 2024

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
Copy link
Author

rzadp commented Aug 26, 2024

A quick follow-up PR: paritytech/polkadot-sdk#5462

@lovelaced
Copy link

@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
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@kianenigma @lovelaced @rzadp