Tracking issues related to `paritytech.github.io`

[kianenigma]

• [ ] Once hosting is clear, this should be hosted elsewhere as well, but we should not cowboy and break break all the links. The existing links must be kept.
• Publishing to docs.rs would also be good. Would also help us with versioning.

- [ ] https://github.com/paritytech/polkadot-sdk-docs/issues/10
- [x] better styles
- [x] fix broken links
- [x] a few missing items: xcm-docs, polakdot implementor's guide
- [x] https://github.com/paritytech/polkadot-sdk-docs/issues/11
- [x] https://github.com/paritytech/polkadot-sdk-docs/issues/9
- [x] Add floating 'Join us on Discord' & 'Join us on Element' social buttons

[kianenigma]

Jun found the repo: https://github.com/paritytech/paritytech.github.io

[kianenigma]

And Erin has mad a great example: https://github.com/paritytech/paritytech.github.io/tree/eg-redo-styles

[kianenigma]

https://paritytech.github.io/xcm-docs/ should be added.

[kianenigma]

https://nostalgic-css.github.io/NES.css/ is arguably a suitable CSS framework for this :)) courtesy of @aaronbassett

[kianenigma]

Here's a more concrete list of action-items:

1. Showcase all of Parity's project, in a nice view. The order matters, we want to have the more important ones first. Each project should get a concise high level description
2. For each project, one should be able to click on a link to go to its gh page, or its hosted rust-docs, if applicable.
3. For each project, the number of starts, daily average commits, LoC, contributors and such should be shown.
4. The same metrics for "3" can be shown in aggregate form as well, with a phrasing of "this is all the code that Parity outputs".
5. As for the issues, we need a section that show a list of latest open issues in substrate, polakdot and cumulus (in the future, the mono-repo) that have a mentor tag. IIRC all 3 repos have this label. Substrate certainly has it.
6. Accompanying this, there should be a link to substrate's contributing and documentation guide.
7. we will later curate a list of further "documentation resources" for external contributors and attach it here.
8. A trophy section can show the list of latest closed issues that have the mentor label.

This implies that we should be more careful with the mentor label, we we easily can. CC @juangirini @ggwpez @the-right-joyce.

[kianenigma]

To get a full list of websites hosted atm, put 'site:https://paritytech.github.io/' in google.

[kianenigma]

Or better: wget --recursive --level=1 https://paritytech.github.io/

[wentelteefje]

The draft is ready: https://wentelteefje.github.io/paritytech-prototype/docs/

Note: Currently, the data is static until I resolve some CSS issues. After this, I plan to configure several workflows which will query the Github API at least hourly.

Still missing:

• Aggregated metrics for all Parity projects
• Links to Github and Rust docs for projects
• Substrate playground, Substrate connect, Contracts-UI, Banana Split, Parity Signer and XCM docs

Issues/Open questions: 1) CSS: The NES.css tables are not as responsive as I expected. It works well on desktop, but on my smartphone, the layout looks unsatisfactory. Need to fix that. 2) Mentor tag: Frontier and Cumulus don't provide a mentor tag or anything similar. ink! offers both a mentor tag and a "good first issue" tag. wasmi, Substrate playground, Substrate connect, Contracts-UI, Banana Split, Parity Signer, and XCM documentation use only the "good first issue" tag. For the open issues list, I'm currently including both "mentor" and "good first issue". 3) Date cutoff for open issues: Some of the open issues are almost three years old. I believe we should set a reasonable cutoff date for including open issues in the table. 4) Missing logos: Having a logo for each project would be ideal, but sadly, some projects don't have one. For these, I'm using a Parity placeholder. 5) Lines of Code (LOC): Without cloning the respective repositories, it's challenging to provide a good estimate for LOC. I will likely clone them locally once and run git ls-files -- '*.rs' | xargs wc -l | sort -n to count the lines of Rust code. With this as a baseline, I can give an approximation based on the additions and deletions of the most recent commits to that repository. However, as this is somewhat of a gimmick, I'm not prioritizing it at the moment.

@kianenigma Please let me what you think!

[kianenigma]

CSS: The NES.css tables are not as responsive as I expected. It works well on desktop, but on my smartphone, the layout looks unsatisfactory. Need to fix that.

FWIW, I really only posted this here because @aaronbassett once mentioned it in a call I found it cool, otherwise you are free to go with any CSS framework you want.

Date cutoff for open issues: Some of the open issues are almost three years old. I believe we should set a reasonable cutoff date for including open issues in the table.

Yes, indeed. Let's leave it as a configuration? Or else, scrape all, but paginate the issues and only show the most recent 1-2 pages. Also, for this, you can limit it to only Substrate+Cumulus+Polkadot+ink!.

[kianenigma]

Some thoughts about the audience:

I suggest keeping in mind that the foremost point of this webpage is to remain as an entry point to our rust-docs. Would be good to keep that in mind.

Also, we can think about categorizing these projects into tiers such that the most important ones are more and more in the spotlight. In reality, we care the most about:

1. Monorepo: Substrate + Cumulus + Polkadot
2. ink!
3. Once ready CAPI.

I think these are really our main tier one projects for the 3 main avenues you can "build" in our ecosystem. Anything beyond these should be somewhat on the sidelines.

---

I am no expert here, but I think it might be good to split this into 2 parts:

1. Page per project, that contains more or less what you have now, but just for one repo at a time. Once we move to a mono-repo, this will be made easier.
2. More importantly, one "doc index directory" page.

[kianenigma]

This section highlights recently resolved mentored issues. Congratulations on your achievements!

I don't know how these are being calculated now, most of the people here are Parity members, not external :D You should probably double check it, and filter them for those that are actually by gh members that are not parity.

[kianenigma]

All in all, the page can be more paginated and be made collapsible. Things like contributors are taking a lot of space, and probable a handful of avatars is enough, and the rest can be expanded if you click on something. Possibly, we can actually focus more on externals and only show:

1. Top 4 contributors within Parity
2. Top 4 contributors external to Parity.

[liamaharon]

Added a TODO for floating Discord, Element, Stack Exchange social links

[KiChjang]

5. As for the issues, we need a section that show a list of latest open issues in substrate, polakdot and cumulus (in the future, the mono-repo) that have a mentor tag. IIRC all 3 repos have this label. Substrate certainly has it.

For more information on this particular point, this is basically an idea that I've been communicating with Kian about for a while, and the inspiration comes from https://starters.servo.org/.

In a nutshell, the purpose of this page is to allow and attract new code contributors to the core repos. If you click on the link for servo starters, you can see that you can filter issues by programming language, and displays all issues from any of the repos under the GitHub servo org. It also has a "I'm feeling adventurous" button there which simply takes people to a random open issue listed on the page.

[kianenigma]

[wentelteefje]

New page is now live at paritytech.github.io.