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
efficient storage
read simplified tutorials, basic rendering of rich content
quick interactive quiz & exercises after each section
full text search similar to https://devdocs.io/ with ranked fuzzy search observing synonyms with context enriched from parents and weighted siblings
cheat sheets for syntax of JavaScript, HTML5, CSS3, Web API, webxdc
API reference
JavaScript console with bookmarks
rewrite those external links to internal ones whose target is included in the bundle
follow internal links
tabbed browsing between multiple document pages, JS console, notepad and source code editor
show a deep link to the respective original source page to enable providing a correction upstream
optional: also usable outside Delta Chat, rendered on a static VCS page (ideally as a single page app that can be saved as a file with a single click)
optional: include the internationalized versions of content that already exists
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.
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.
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.
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.
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.
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.
I’m not unconditionally against bundling HTML instead of a more frugal markup. Good compression of either ought not result in a difference more than a few percent and also friendly to sliding-window based methods (i.e., **something** vs <b>something</b>).
However, I have a feeling that the “pretty” HTML they generate might be kind of bloated with a more notable difference. Implementing a step that both prunes the fat and ensures the output between the individual sources will look consistent would probably be more work than implementing very simple markdown-like rendering from scratch.
Don’t worry about markup processing. I had implemented quite a few Markdown parsers & renderers for. I would focus on allowing indexing the content and for a user to read it, postponing improvements to later date. It would already be mostly readable as a proof of concept if links and section headings were handled and line breaks added between paragraphs - taking just a few lines of code with regexp!
For a minimal viable product, a slightly altered gemini (gemtext) renderer would accomplish 95% of the value for 5% of the work with surprise-free error cases remaining using just a few pages of code. Some simple additions would be in order, such as inline links and maybe the most straightforward cases for inline markup (bold, italic, code), but that’s still doable in a few lines of code. We can skip nested lists and tables for now.