Skip to content

Restructure the README: a short README, and a page in docs/ for each part #24

Closed

Description

@alekswebnet

The README is the only documentation of this repository, and it has grown into a design document: 116 lines, 2,100 words. What the site serves, how to run it and how it is built take its first 30 lines. Then come four long sections on the parts (the pdfjs-viewer docs, the H5P build page, the bundles, the skill), each with its reasons, its history and what was measured. What the site pins and how a pin moves, which is most of the upkeep, is not in it at all.

It is also behind:

  • It says embed-my.github.io's /build "becomes a redirect here that keeps the fragment, … deployed once this page is live". It is one: a visit there goes on here with its fragment.
  • The skill section does not say that /h5p/skill/ also lists the build tool and every bundle (List the build tool and every bundle on the skill page #18), or that, since h5p-author 0.9.1, SKILL.md sends a chat that has its text alone there first.
  • Nothing says that the type files are served twice, at /h5p/build/types/ and under /h5p/skill/references/types/, from the same package.
  • Nothing says which package feeds which page, that Dependabot takes @missing-elements releases the day they come out (.github/dependabot.yml, pnpm-workspace.yaml), or how a pin moves. pnpm typecheck is not listed.
  • "A container's up to 8.4 MB" is not right: the largest bundle is H5P.KewArCode's, 8.4 MB, and the largest container's, Branching Scenario's, is 7.7 MB.

The README should say what the site serves, how to run it, how it is built and what it pins, and point to a page for each part.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions