draft proposal to restructure chapters

[ansuz]

This is a WIP draft of a PR to follow up on my proposal to split some chapters into smaller sections. I intend to clean it up a little more, but I wanted to validate the overall structure before putting in more effort.

A general overview:

1. the Webxdc Specification describes the spec from the perspectives of both a webxdc app developer (assumed to be a relative novice or hobbyist level of expertise) and a messaging app developer (who I'll refer to as a platform dev) who is considering implementing webxdc support in their client. There is some overlap between the two, which is reasonable, but I think the language differs significantly. The beginner-friendly sections use plain language, while the notes for platform dev read more like an RFC (with terms like SHOULD, MUST, etc.). I haven't separated these sections yet, but I think it might be worthwhile to do so.

2. The specification section also covered the state of a number of webview APIs as both DOs (localStorage, indexedDB, visibilityChange, etc.) and DON'Ts (beforeunload, document.cookie, open, alert, prompt). I believe these are more appropriately grouped under Compatibility in the Tips & Tricks section, where there was already a mention of using babeljs to transpile to a portable subset of js.

3. My original intention was to introduce a new section about synchronizing shared state via CRDTs, which would have been too long on its own to simply include into the Tips and Tricks section as it was. In the proposed structure this will get its own page, but for now I only have a placeholder with a very rough content outline.

4. I understand that these sections were originally grouped together with the intent of avoiding very small pages. In its current state there is a selfAddr_and_selfName section which is considerably shorter than the others, however, I think it could easily benefit from some additional description. For example, neither API describes the data-type of the id or name. I believe they are strings, but that isn't explicit. It would probably benefit both app and platform developers to describe the behaviour in existing implementations, along with situations where either value might be useful.

That's all for now. I don't think Intro, Get Started, or FAQ justify being split up. Personally I find it easier to get an overview of the spec and tips section with the sub-headings in the sidebar.

Any thoughts/questions/objections before I proceed further?

[hpk42]

On Sat, Oct 14, 2023 at 06:03 -0700, ansuz wrote:

This is a WIP draft of a PR to follow up on my proposal to split some chapters into smaller sections. I intend to clean it up a little more, but I wanted to validate the overall structure before putting in more effort.

A general overview:

1. the Webxdc Specification describes the spec from the perspectives of both a webxdc app developer (assumed to be a relative novice or hobbyist level of expertise) and a messaging app developer (who I'll refer to as a platform dev) who is considering implementing webxdc support in their client. There is some overlap between the two, which is reasonable, but I think the language differs significantly. The beginner-friendly sections use plain language, while the notes for platform dev read more like an RFC (with terms like SHOULD, MUST, etc.). I haven't separated these sections yet, but I think it might be worthwhile to do so.

+1

2. The specification section also covered the state of a number of webview APIs as both DOs (localStorage, indexedDB, visibilityChange, etc.) and DON'Ts (beforeunload, document.cookie, open, alert, prompt). I believe these are more appropriately grouped under Compatibility in the Tips & Tricks section, where there was already a mention of using babeljs to transpile to a portable subset of js.

+1

3. My original intention was to introduce a new section about synchronizing shared state via CRDTs, which would have been too long on its own to simply include into the Tips and Tricks section as it was. In the proposed structure this will get its own page, but for now I only have a placeholder with a very rough content outline.

+1

4. I understand that these sections were originally grouped together with the intent of avoiding very small pages. In its current state there is a selfAddr_and_selfName section which is considerably shorter than the others, however, I think it could easily benefit from some additional description. For example, neither API describes the data-type of the id or name. I believe they are strings, but that isn't explicit. It would probably benefit both app and platform developers to describe the behaviour in existing implementations, along with situations where either value might be useful.

That's all for now. I don't think Intro, Get Started, or FAQ justify being split up. Personally I find it easier to get an overview of the spec and tips section with the sub-headings in the sidebar.

yes, sounds good. Looked at the output. Still can't quite believe that having sub-headings in the sidebar requires that sub-headings have their own file instead of mdbook pulling in the subsection titles into the TOC but we can check that later. In any case, the new structure is easier to navigate.

Any thoughts/questions/objections before I proceed further? You can view, comment on, or merge this pull request online at:

https://github.com/webxdc/webxdc_docs/pull/80

-- Commit Summary --

• draft restructure of spec and tips & tricks

-- File Changes --

M src/SUMMARY.md (20)
D src/spec.md (346)
A src/spec/README.md (97)
A src/spec/importFiles.md (52)
A src/spec/selfAddr_and_selfName.md (27)
A src/spec/sendToChat.md (60)
A src/spec/sendUpdate.md (41)
A src/spec/setUpdateListener.md (34)
A src/tips_and_tricks/README.md (10)
A src/tips_and_tricks/compatibility.md (46)
R src/tips_and_tricks/debugging.md (95)
A src/tips_and_tricks/packaging.md (24)
A src/tips_and_tricks/shared_state.md (17)
A src/tips_and_tricks/typescript_support.md (54)

-- Patch Links --

https://github.com/webxdc/webxdc_docs/pull/80.patch https://github.com/webxdc/webxdc_docs/pull/80.diff

-- Reply to this email directly or view it on GitHub: https://github.com/webxdc/webxdc_docs/pull/80 You are receiving this because you are subscribed to this thread.

Message ID: @.***>

[hpk42]

however, i don't want to stop your work -- so if the internal links are fixed we can merge and see if any external links really break and if there is a technique to prevent this (a redirection list or something).

[ralphtheninja]

@ansuz @hpk42 Is it possible to preview these changes in an easy way online or do I have to run it locally?

[ansuz]

@ansuz @hpk42 Is it possible to preview these changes in an easy way online or do I have to run it locally?

I think it has to be run locally, though I can deploy it somewhere temporarily for easier review

[ralphtheninja]

@ansuz @hpk42 Is it possible to preview these changes in an easy way online or do I have to run it locally?

I think it has to be run locally, though I can deploy it somewhere temporarily for easier review

That would be awesome if you have time and energy for that!

[ansuz]

this is the current state, including some fixes for broken links that I haven't committed yet: https://demo.cryptography.dog/

[ralphtheninja]

I really like the more fine grained menu to the left.

The packaging page looks a bit odd though:

[ralphtheninja]

I understand that you basically just split the content and didn't change the formatting anything. Maybe we should / could discuss this further after merge. It was just something that caught my eye right now.

[ansuz]

The packaging page looks a bit odd though:

agreed. I think there's a number of things we could probably group together with it, though. Maybe some more information about what should go in manifest.toml? That's described in this section, though that information seems to be written more with platform devs in mind.

Maybe in the future it can contain more tips about how to update? or recommendations for import/export functionality?