Rationale.md

[knimura]

Intention of the rational.md is explaining the rational of scripting API and it would be reflected to current practice document eventually.
Some parts relates to the synchronization TF that may input to the architecture document.
How should we deal a section of “how scripting API works”?

https://w3c.github.io/wot-scripting-api/rationale

[zolkis]

Based on current practice in other Web specifications, rationale for Scripting API is to explain why the design decisions have been made the way they are. It is for people who wonder why we expose things a certain way. If they read the rationale and agree, case solved. If not, they can file an issue.

The rationale document is usually meant for spec developers and API users, for background explanation that can be references and can save time by not having to explain every time why things are the way they are.

The word "rationale" has been used in the past in the WoT IG with a slightly different meaning, to show use cases that explain what the IG needed to define or explore.

The rationale document currently covers:

• How the Scripting API works, through use cases.
• Rationale for Scripting API.

IMHO the document named "rationale" should contain only the second, and we should have a separate document (name pending, e.g. "usecases") that lists the first part (still applies to Scripting API).

Then, the explanatory text about runtimes, algorithms, "how it works" should be in the API specification.

However, we could have an "examples" document that would take some code examples and explain how the API works: how apps business logic is done with the API, how the implementation plugs into the underlying platform, for instance how security, script provisioning, protocol bindings etc work.

Also, we could have a document for implementors that covers recommendations on how to implement certain features (e.g. "stopping" a discovery based on broadcast, or security considerations etc).

All these could also be chapters in a doc, but if a doc gets too long, it's better to split and be referred from a master doc.

[h0ru5]

we discussed this in the weekly webconf and decided to split it into a primer (explainer) and rationale.
addressed in PR #19

[zolkis]

We can close this.