Skip to content

README is absurdly large and unintuitive #1053

Open
@jhmaster2000

Description

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

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions