Request for packaging a WebXDC tutorial and reference materials

Mini Apps
,
1

Goals

Being exhaustive is not a goal, so it is acceptable to skip parts which are more advanced or not needed for contributing to and creating simple webxdc apps.

Maintenance

To ensure long term maintainability, it ought to be built automatically from the sources, not by hand, so it could assimilate upstream updates. Hence, some kind of templating and higher level editing instructions might be useful. For example, it could be marked up to cut out sections or assemble multiple pages into one or how to fix up relative links.

Features

  • read simplified tutorials
  • quick interactive quiz & exercises after each section
  • full text search similar to https://devdocs.io/
  • cheat sheets for syntax of JavaScript, HTML5, CSS3, Web API, webxdc
  • API reference
  • JavaScript console with bookmarks
  • optional: provide all phases of creating webxdc on the device without servers: edit source, preview (limited), compress to zip, send to chat
  • optional: an IDE or code paste pad with token highlighting, static code analysis and syntax error checking to develop simple apps (PoC: use eval and parse the exception)
  • Aim for a file size less than 1MB. The whole aim is to provide a TL;DR for those who don’t want to go through the whole curriculum, so if it needs so many words to describe well, we are doing it wrong.

Sources

As a proof of concept, we may prioritize not writing any new documentation at all. Rather, we should package all or parts of the most important existing documentation in the area into a single webxdc.

Assimilating non-FOSS resources is not possible, but it may inspire others to fill in the gaps when phrasing our own exercises for example.

FOSS resources

Non-commercial copyleft resources

Distributable resources

Related tools

2

For the docs you probably want something similar to this site.

1 Like
3

Yes, although I dislike that they overload the MDN website to scrape the docs instead of just cloning the source repo and rendering it themselves - this is akin to what abusers are doing to the web at large now for different reasons. And the more complicated question of how to best take subsets is still open.

4

I took a look at GitHub - mdn/content: The official source for MDN Web Docs content. Home to over 14,000 pages of documentation about HTML, CSS, JS, HTTP, Web APIs, and more. · GitHub content and it seems that you can fit all the html, css and javascript markdown content into a ~ 10mb zip, this is including tutorial, guides, how-to and some images, if you only keep the reference then you can probably lower it to 8 or less.

But web APIs only make a ~ 16 mb zip, even if you can remove some of the APIs you know you are not going to need in webxdcs i don’t think it can all fit in one webxdc, you would need at least 2.

5

Btw, this may be relevant GitHub - pryzrack/xdc-md-view: markdown visor for Deltachat · GitHub, you replace the content in `/data` with markdown files, but it seems like mdn content needs a built step or the markdown is more advanced, so this webxdc can’t render it all.

6

All 14187 markdown files (without attachments) within that repository contains only 893k of text and compresses down to 92kB with gzip. That said, I don’t think we would need 99% of the files there if we aim low enough. No beginner would bother seeking through even a tiny fraction of that.

If we needed some of the more useful media (such as sketches of CSS terms), we could optimize its scale and compression or recreate them in vector format (such as using HTML & CSS…), but probably only if we are in dire need for space. After closer inspection, most space is taken up by unnecessary and low information content png decoration.

Also note that packing all docs into a single file improves compression ratio compared to lots of tiny individual files. Additionally, we could even compress the content with xz and self-extract upon access. The above sample compresses to 77kB with xz, but surely it doesn’t make sense with such a small amount of data.

7

At the same time, could we agree on a reduced scope to both lessen the cognitive load on beginners targeted and to improve the cross-platform compatibility of the created code?

For example, do you see any drawback with only covering technologies already available on both Android 5 (Chrome ~37) and KaiOS (Gecko 37) for example? We could go even lower as nothing stops you from implementing perfectly usable games in ES6 (ES2015) as long as you have capabilities for canvas, audio and touch.

And as an unpopular opinion, I dare say that one could also implement perfectly enjoyable games without touching canvas or webgl at all! Maybe also some simple gimmick web API such as optional vibration, but definitely not hundreds of them.

Despite not focusing on gathering guides for those or linking them prominently from the guide main page, the respective API pages could still be returned by the search feature if they only take a few dozen kilobytes of extra space anyway.

8

Well, that’s great then, i must have compressed with some attachments when i tested.

If it is really that small, then it maybe makes sense to check how big it is the html after the build step, if it is small enough (less than 5mb) it could be used directly to avoid having to implement markdown previewer. I could not check myself because i got errors while installing dependencies.