Feedback on the WoT Integration guide and blog post

[egekorkan]

While reading https://www.eclipse.org/ditto/basic-wot-integration.html and https://www.eclipse.org/ditto/2022-03-03-wot-integration.html I have spotted some issues which are borderline nitpicky:

Guide:

• I had seen a demo of the integration working on @thjaeckle 's laptop but without that or reading until the end of this document with the curl requests, it is not clear what the integration means. I think adding something like "This integration allows for Ditto clients or usual WoT clients to obtain TDs for the Ditto-managed twins" or like what is described in https://www.w3.org/WoT/developers/ "Ditto managed digital twins can be linked to WoT Thing Models from which Ditto can create Thing Descriptions containing the API descriptions of the twins. "
• Multiple places use thing without capital T. My suggestion would be to always capitalize it to differentiate WoT/IoT Things from colloquial use of the word thing.
• I find the point and subpoints at https://github.com/eclipse/ditto/blob/6ebbe7e2da9c7f82405ab7676c1f43358d464eba/documentation/src/main/resources/pages/ditto/basic-wot-integration.md?plain=1#L79 a bit confusing:

if backed by a WoT Thing Model, the twin will tell you as response exactly
what it is capable of
which HTTP endpoints to invoke to access data / send messages

I do not understand what is meant by the response. Also, TMs do not necessarily have HTTP endpoints and this documentation even says that at https://github.com/eclipse/ditto/blob/6ebbe7e2da9c7f82405ab7676c1f43358d464eba/documentation/src/main/resources/pages/ditto/basic-wot-integration.md?plain=1#L54

• The points under The benefits of adding such a “Thing Model” reference to digital twins managed in Ditto are: start with a different form of a sentence, i.e. some start with a verb, some with a noun, the last two change from a singular person to a plural person (lack of s at the verb)

• At https://github.com/eclipse/ditto/blob/6ebbe7e2da9c7f82405ab7676c1f43358d464eba/documentation/src/main/resources/pages/ditto/basic-wot-integration.md?plain=1#L83 it would be better to always write JSON instead of Json . This happens in other places as well

• At https://github.com/eclipse/ditto/blob/6ebbe7e2da9c7f82405ab7676c1f43358d464eba/documentation/src/main/resources/pages/ditto/basic-wot-integration.md?plain=1#L87

  • perform -> performs
  • it would be nice to say that even the meeting minutes are totally public and that specifications develop over GitHub, making it open to review. I am a bit "nitpicky" about this since way too many standards claim that they are open but in the end, only the pdf/webpage of the standard is available for free.

• tiles -> titles at https://github.com/eclipse/ditto/blob/6ebbe7e2da9c7f82405ab7676c1f43358d464eba/documentation/src/main/resources/pages/ditto/basic-wot-integration.md?plain=1#L133

Blog Post:

• public -> publicly at https://github.com/eclipse/ditto/blob/6ebbe7e2da9c7f82405ab7676c1f43358d464eba/documentation/src/main/resources/_posts/2022-03-03-wot-integration.md?plain=1#L56

[thjaeckle]

Thx for the awesome feedback, @egekorkan - will incorporate it 👍