Documenting Design Decisions

[egekorkan]

I have recently gotten feedback that some features are not clear why they are done like that. An example is:

• Why do we have operations like readproperty and writeOnly/readOnly at the same time?

The answer can be known to us but not to newcomers. The table at https://w3c.github.io/wot-thing-description/#sec-op-data-schema-mapping also does not explain why both exist at the same time.

So the overall discussion I want to have is about multiple points:

• Is it the job of the TD spec to do this? If not, where should this happen?
• How can we link to use cases, requirements and issues that bring a feature into the spec? If we add new features, it should be clear to anyone why we added them. My guess is that there will be an issue for all such points.
• We should document all such feedback in someplace. Some of the other questions I get are:
  • When to use links and when to use semantic annotations?
  • What is the use of the @context
  • What happens when readOnly and writeOnly are true at the same time? There are many questions about terms we get from JSON Schema.
  • and more. This list is just to exemplify and is not the final place for this.

Note: Please do not comment to give answers to design decisions themselves but comment about the overall process.