core-js
core-js copied to clipboard
zloirock
README is absurdly large and unintuitive
Yeah... that's about it. The issue is it causes browsers low-end or even medium-end devices, especially mobile devices, to lag or even completely freeze when trying to load core-js' GitHub repository homepage, or anywhere else that embeds core-js' README, which is a terrible accessibility problem. (and also a little ironic in how a library geared towards supporting old systems fails to do so with the most basic thing like a README)
For a reference benchmark, the current core-js GitHub homepage (https://github.com/zloirock/core-js) will completely freeze my browser for roughly a full minute before the README is fully loaded in, with my specs listed below:
- OS: Android 11 aarch64
- CPU: Qualcomm ATOLL-AB (8) @ 1.804GHz
- RAM: 6GB
- Browser¹: Opera 67, Firefox 97, Chrome 98 ¹: Tested in multiple browsers to ensure it isn't a browser-specific issue, although timings were not consistent (Opera freezes for a full minute, Firefox for around 20s, Chrome for around 10s but keeps stuttering upon scrolling), they all froze for some period of time nonetheless.
As you can see my system a quite decent medium-end system, so I can only fear for those on the lower end. I urge you to consider matching the GitHub README to the npm README, short, concise, and performant. The remaining information on the current README (the documentation part, which is 90% of it) should be split up into multiple smaller .md files properly organized in a folder structure inside the /docs/ folder which already exists on the repository, and only being used for the core-js@3 announcement, which can coexist with the additions. This would make the docs modular and easier to navigate aswell, so it's a win-win even for those on high-end systems that would never notice this to be a problem. Just imagine if MDN decided to put all their docs into a single monolithic markdown file... even if your PC could handle loading it, it would still suck to traverse.
At first, it's an issue of GitHub and Chrome if a device with 6GB RAM and enough fast CPU can't properly show 170kb document.
However, I agree with you. The initial page is unintuitive and too large.
But, for improving readability, I'm not a tech writer. It's an open-source project - feel free to help with improving documentation.
I'm thinking for a long time about splitting it as you propose - but it will break many and many thousands of links from other websites to the corresponding parts of the documentation, so I think that it's better to delay it to the next major release.
Yeah I agree there's definitely a browser-side issue with poor optimization here, mainly mobile browsers I guess, but that's a far too upstream issue that would be a much bigger hassle and timespan to get resolved, if at all.
Breaking links such as MDN's is indeed a concern I had but forgot to include in the issue when writing it, one potential solution I thought of is, the links target specifically the markdown headers of each section, so those are all that really needs to stay on the README to maintain the links, all the actual text content of each section can be safely transferred, and the section headers would be turned into hyperlinks linking to their respective file containing their actual content. This would already drastically cleanup the README and reduce it's size, whilst maintaining the external links and almost seamlessly integrating them with the new modular docs system with no changes required on their end, saving everyone a lot of time, and it would probably continue to be maintainable as an "Index" to the core-js documentation for the foreseeable future, thoughts?
LGTM. The manual redirect approach is not perfect, but it's the best we can do for this specific scenario. A nice side effect of this approach is that eventually all external links to the index will be updated to point directly to the individual files, which can help with the transition process, to remove the manual redirects
I opened a PR for this. But I realized GH has a "Wiki" feature. Should we use that instead?
Thanks. I don't think that GH Wiki is a good option for many reasons. In the case of using simple .md files as docs, at least, the version of docs pinned to the required core-js version by tag / branch and it can be simply moved to an alternative hosting.
GitHub wiki is cumbersome to work with.
Maybe something like https://rust-lang.github.io/mdBook/index.html?
- Docs files are in markdown, not much changes needed.
- Docs pages can be published at https://zloirock.github.io/core-js/.
- GitHub Actions can be used to automatically publish updated docs pages.
- Docs pages displays well on mobile.
- Docs pages has navigation sidebar.
- Docs pages has search.
- Docs pages has "Suggest an edit" link.
- Docs pages has "Repository" link.
- Docs pages has "Print" link. Lets you print out your latest copy of core-js documentation, which you can tape onto the walls of your room which is now a JavaScript themed cocoon.
Maybe something like https://rust-lang.github.io/mdBook/index.html?
files are in markdown pages can be published at https://zloirock.github.io/core-js GitHub Actions can be used to automatically publish updated docs pages pages displays well on mobile "Repository" link
That's similar to how MDN does it, I agree that it would be a good idea. However, the following points:
navigation sidebar search ~~"Suggest an edit"~~
Are not included (AFAIK), they must be implemented manually in the source code
Update: After using GHP for more stuff, I noticed there is a built-in "edit" button! (only for markdown files)
I'd be interested in helping.
Personally my first pick would be Astro, here's the repo for their docs site, which could be used as a starting point, though that might be overkill: https://github.com/withastro/docs
They also have a docs starter: https://github.com/withastro/astro/tree/main/examples/docs
Docusaurus would also be a solid choice, though when I was evaluating it recently, I ran into several issues that seemed to be related to it having a lot of old versions of dependencies: https://github.com/facebook/docusaurus#readme
Either way, an easy way to do search for open-source docs is Algolia Docsearch: https://docsearch.algolia.com/
The application process can take "up to 2 weeks", and I think the website would need to exist first, so it's a bit of a chicken-and-egg thing.
I've been playing around with MiniSearch recently, it seems decent, that would be another option if you don't fancy Algolia: https://github.com/lucaong/minisearch
I can do a crude MiniSearch POC, to at least find out how big the index would be.
I've been meaning to see how MDN is powering their search...
Vitepress might be the best solution. The switch shouldn't be difficult since the doc is already written in markdown. Just need to split that huge readme but it looks like #1095 already did it.
@strugglesharp
terrible life VS freeze browser?
wtf?
Do you mean VSC online freezes when opening this README?
@AverseABFun-windows it will be required, but not right now - initially, I should think about the static site generator and the frame of the site. Now you could help with docs in the repo.
Ok!
On Friday, February 17, 2023, Denis Pushkarev @.***> wrote:
@AverseABFun-windows https://github.com/AverseABFun-windows it will be required, but not right now - initially, I should think about the static site generator and the frame of the site. Now you could help with docs in the repo.
— Reply to this email directly, view it on GitHub https://github.com/zloirock/core-js/issues/1053#issuecomment-1434689233, or unsubscribe https://github.com/notifications/unsubscribe-auth/ATOOUFR2ZY5SIB36T6BDBXTWX574NANCNFSM5PXBHDNA . You are receiving this because you were mentioned.Message ID: @.***>
I'm going to try a first build using vuepress2 + hope theme in my fork, which should be ready soon
K
On Monday, February 20, 2023, 冰雪殇璃陌梦 @.***> wrote:
I'm going to try a first build using vuepress2 + hope theme, which should be ready soon
— Reply to this email directly, view it on GitHub https://github.com/zloirock/core-js/issues/1053#issuecomment-1437086457, or unsubscribe https://github.com/notifications/unsubscribe-auth/ATOOUFSABHE7TXMUPEUSP73WYN3WHANCNFSM5PXBHDNA . You are receiving this because you were mentioned.Message ID: @.***>
@zloirock It seems that Vuepress-theme-hope also indirectly depends on core-js.
So npm directly references unbuilt packages in the workspace and causing errors.
To fix this, we may have to switch to pnpm, which allows us to choose to prioritize packages from the registry.
What do you think about this?
@DreamOfIce there are some reasons why I'm against pnpm usage. What's the problem to build packages before usage?
there are some reasons why I'm against
pnpmusage. What's the problem to build packages before usage?
Use remote core-js even if the version matches (since the version in workspace is probably not built)
As a side note, this feature is also supported by yarn
I don't think that it's a big problem to run npm run init before the static site generation (and bundle-package in core-js-bundle is required), so I'm not sure that I understand the problem.
I don't think that it's a big problem to run
npm run initbefore the static site generation (andbundle-packageincore-js-bundleis required), so I'm not sure that I understand the problem.
How about adding a script prepare to point to npm init so that it can be initialized automatically when running npm install?
https://github.com/zloirock/core-js/commit/b457824031f8956f7695eaf2e65951fe81a6fa13
@zloirock I've roughly done the front page, what do you think ~~(the logo seems to have been accidentally damaged)~~: corejs-doc.netlify.app I'll split and group the documents in the next few days if that's okay
unintuitive
I only agree with unintuitive part. I tried using my 6 years old samsung android phone with google chrome on it and slow mobile internet and it worked fine.
@zloirock I've roughly done the front page, what do you think ~(the logo seems to have been accidentally damaged)~: corejs-doc.netlify.app I'll split and group the documents in the next few days if that's okay
Wow, that's a big improvement. Tho I would think again about that background animation on main page those 4 blocks at the bottom. The scale part and icons are good, but those diagonal flashing lines... Also is that possible to simplify instructions for contributors? Like split them up in a few categories or something? Maybe depends on type of contribution or somehow else. And put a step by step guide in each one. I'm getting lost in those 25 different files you need to keep in mind lol I assume you only need a few for each type of contribution.
What do you guys think on hosting a website for free since its small and front end only? Keep github page structured the way it is but add a link to website? This way all current users and projects will not be affected and for new people like me it will be a whole lot easier to figure out what's goin on here.
@zloirock I've roughly done the front page, what do you think ~(the logo seems to have been accidentally damaged)~: corejs-doc.netlify.app I'll split and group the documents in the next few days if that's okay
Wow, that's a big improvement. Tho I would think again about that background animation on main page those 4 blocks at the bottom. The scale part and icons are good, but those diagonal flashing lines... Also is that possible to simplify instructions for contributors? Like split them up in a few categories or something? Maybe depends on type of contribution or somehow else. And put a step by step guide in each one. I'm getting lost in those 25 different files you need to keep in mind lol I assume you only need a few for each type of contribution.
What do you guys think on hosting a website for free since its small and front end only? Keep github page structured the way it is but add a link to website? This way all current users and projects will not be affected and for new people like me it will be a whole lot easier to figure out what's goin on here.
Thanks for the advice, I'll take it into consideration! This site is still a work in progress at the moment and a lot of it has yet to be optimized Also, this demo is currently deployed for free on netlify
I'm gradually realising that there's a bit more to do with the documentation, so I'm putting a simple roadmap here now and I'll update it from time to time
- [x] Complete the basic layout
- [x] Porting compatibility page
- [ ] Splitting and optimising the user guide (reference or reuse https://github.com/zloirock/core-js/pull/1095 )
- [ ] Splitting and optimising contributions guide
- [ ] Update the links to the documentation in the project
- [ ] Complete Chinese translation (long term) If you have any suggestions feel free to reply and contribute 😄