README is absurdly large and unintuitive

[jhmaster2000]

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.

[zloirock]

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.

[jhmaster2000]

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?

[Rudxain]

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

[Rudxain]

I opened a PR for this. But I realized GH has a "Wiki" feature. Should we use that instead?

[zloirock]

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.

[joshxyzhimself]

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.

[Rudxain]

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)

[mrienstra]

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

[Elliot67]

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?

[Rudxain]

@strugglesharp

terrible life VS freeze browser?

wtf?

Do you mean VSC online freezes when opening this README?

[AverseABFun]

I can help with this, what is the plan? Astro, docusaurus, what?

[AverseABFun]

I can help with this, what is the plan? Astro, docusaurus, what?

[zloirock]

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

[AverseABFun]

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

[DreamOfIce]

I'm going to try a first build using vuepress2 + hope theme in my fork, which should be ready soon

[AverseABFun]

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

[DreamOfIce]

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

[zloirock]

@DreamOfIce there are some reasons why I'm against pnpm usage. What's the problem to build packages before usage?

[DreamOfIce]

there are some reasons why I'm against pnpm usage. 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

[DreamOfIce]

It would be great if npm could also do this 😄

[zloirock]

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.

[DreamOfIce]

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.

How about adding a script prepare to point to npm init so that it can be initialized automatically when running npm install?

[zloirock]

It makes sense.

[zloirock]

https://github.com/zloirock/core-js/commit/b457824031f8956f7695eaf2e65951fe81a6fa13

[DreamOfIce]

@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

[Yevgeniy-C]

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.

[Yevgeniy-C]

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

[DreamOfIce]

@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

[DreamOfIce]

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 😄

[zloirock]

@DreamOfIce maybe you will add a PR and we will coordinate it in it's scope?

[DreamOfIce]

I will create a pull request after the guide section is completed

[Rudxain]

I recommend opening a "draft" PR for the new website

[Rudxain]

BTW, @zloirock & @DreamOfIce:

• Should I sync #1095 with upstream? (this will make migration easier because the docs will be up-to-date)
• Or should I wait to contribute to the future PR?

[zloirock]

@Rudxain it's better to do it in the scope of the future PR.

[DreamOfIce]

BTW, @zloirock & @DreamOfIce:

• Should I sync Split README into files located at /docs #1095 with upstream? (this will make migration easier because the docs will be up-to-date)
• Or should I wait to contribute to the future PR?

I've worked on merging your changes locally and will submit and push them out in the next couple of days. Once this is done I will open a draft PR

[Inwerpsel]

Just want to float a suggestion that I didn't find mentioned yet: using the <summary> and <details> elements on the existing main README. This is a minimal change that allows to preserve all content and link anchors present on this page but still hide large detailed chunks by default. It has some drawbacks too but might be overall worth it here.

Advantages:

• Minimal change to content needed, nothing is really removed
• Links to inner sections continue working, and open the relevant section by default (not sure in all browsers though)
• Widely supported (and seems it should fall back gracefully if support is completely absent, but I didn't test this)
• Should definitely improve loading performance at least partially and maybe completely
• Should improve UX and ability to find the most important information

Drawbacks:

• Searching on a page (ctrl+f) does not give results unless the details are opened
• Default appearance sometimes makes it easy to overlook
• Too many collapsibles can be confusing and tedious
• Specifically when accessed through a link, the user never sees it was opened for them and might return to the page and not find what they need (then again, if the default state is much smaller they should quickly notice the <summary> elements)

[Rudxain]

<summary> and <details>

I think this is the best temporary solution. "Temporary" because it's a quick patch that can be applied while the PRs aren't merged

[soryy708]

Any news about this? It's been a while and the readme is still absurdly large.

Edit: I see that the latest work is in https://github.com/zloirock/core-js/pull/1221 but it's stuck in merge hell.

[AlexMelw]

As some of you know, Vite 5 deprecated CommonJS (CJS) and forced us to update to use ESM imports.

After adding "type": "module" to package.json, I've noticed that if I load core-js modules at the top of the entry point of my application, I can no longer specify the directory only:

import "core-js/stable";

Now I have to include index.js at the end:

import "core-js/stable/index.js";

I guess we might/should update the README.md to reflect these changes because I'm not the only one who finds this situation confusing.

[jhmaster2000]

@AlexMelw that would be caused and solved by #893, since it's a planned fix probably not worth it to instruct people at large to switch syntax just to have to switch back later on v4.

[nitinjangra]

Can we remove some lines related to IE11 as its deprecated https://github.com/zloirock/core-js/blob/master/README.md?plain=1#L364 ? correct me if i am wrong but i feel we can remove Chrome 71 version related things as its been standard and no one will be on that very old version

[zloirock]

@nitinjangra apparently, you have no idea how many people are still forced to support IE11 for one reason or another, how often someone writes to me about it, and how many people use core-js to ensure its support.

Chrome 71 in the docs definitely should be updated to an actual version, but not removed, since it's just an example.

[JX75]

I use CoreJS together with TypeScript in a C++ MFC application based on ActiveX, dating from circa 2000. Thanks for your work. You are right, people have no idea. I'm still angry at people from MDN who saw fit to remove all information regarding IE11.