Merge pull request #230 from Tedoshiii/teodor-website-graphic-captions

WoT Tutorial Website - Formatting Changes

Author: egekorkan

Tutorials/whatiswot/website/docs/intro.md

@@ -6,7 +6,7 @@ sidebar_label: Tutorial Introduction
 
 <iframe width="100%" height="400" src="https://www.youtube.com/embed/fk6Il38SybI?si=1J9X3muwlZ5HWYjE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-<a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/1-WoT/1-WoT.mp4">Click here if YouTube does not work go to our GitHub.</a>
+If YouTube does not work, <a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/1-WoT/1-WoT.mp4">click here to watch from our GitHub repository.</a>
 
 <br />
 <br />

Tutorials/whatiswot/website/docs/preliminary/json-schema/intro.md

@@ -6,7 +6,7 @@ sidebar_label: Introduction
 
 <iframe width="100%" height="400" src="https://www.youtube.com/embed/BPqDBu6fT-0?si=L-sz7baJzoAqjo3b" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-<a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/5-JSON_Schema/5-JSON-Schema.mp4">Click here if YouTube does not work go to our GitHub.</a>  
+If YouTube does not work, <a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/5-JSON_Schema/5-JSON-Schema.mp4">click here to watch from our GitHub repository.</a>  
 
 <br />
 <br />
@@ -29,7 +29,9 @@ JSON Schema serves as a JSON document that describes and validates the structure
 
 Its main purpose is to provide guidance to senders, such as clients, on the expected format of their requests, while enabling receivers to automatically validate incoming payloads. Despite being JSON itself, JSON Schema serves as metadata.
 
-![json schema diagram](/img/tutorial/JSON-Schema/schema.png)
+<figure id="fig-json-schema">
+<img src="/img/tutorial/JSON-Schema/schema.png" alt="JSON Schema overview" />
+<figcaption><strong>Figure 1.</strong> JSON Schema overview.</figcaption> </figure>
 
 For instance, a basic JSON Schema like "type": "array" specifies that it accepts an array type in other JSON documents. Similar specifications can be defined for other data types in JSON, such as:
 
@@ -38,9 +40,11 @@ For instance, a basic JSON Schema like "type": "array" specifies that it accepts
 - boolean
 - null
 
-During the validation process on the receiver's end, this schema ensures that the incoming data conforms to the specified structure. Below is an example of how such validation can be implemented in JavaScript:
+During the validation process on the receiver's end, this schema ensures that the incoming data conforms to the specified structure. [Figure 2](#fig-json-schema-validation) serves as an example of how such validation can be implemented in JavaScript:
 
-![js-schema](/img/5-JSON-Schema/js-schema.png)
+<figure id="fig-json-schema-validation">
+<img src="/img/tutorial/JSON-Schema/schema.png" alt="Example of JSON Schema Validation" />
+<figcaption><strong>Figure 2.</strong> JSON Schema validation in JavaScript.</figcaption> </figure>
 
 It can look different in other programming languages.
 For instance in Python:

Tutorials/whatiswot/website/docs/preliminary/json-schema/practice-advanced.md

@@ -6,7 +6,7 @@ sidebar_label: JSON Schema in Practice - Advanced Topics
 
 <iframe width="100%" height="400" src="https://www.youtube.com/embed/gZa2vxmrm4Q?si=6SVnfrqxF-H_dQhB" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-<a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/7-JSON_Schema_in_Practice_2/7-JSON-Schema-Demo.mp4">Click here if YouTube does not work go to our GitHub.</a>  
+If YouTube does not work, <a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/7-JSON_Schema_in_Practice_2/7-JSON-Schema-Demo.mp4">click here to watch from our GitHub repository.</a>  
 
 <br />
 <br />

Tutorials/whatiswot/website/docs/preliminary/json-schema/practice-validators.md

@@ -6,7 +6,7 @@ sidebar_label: JSON Schema in Practice - Validators
 
 <iframe width="100%" height="400" src="https://www.youtube.com/embed/ZKoWLyaWuaw?si=Qo-mBPkp8-J33o7C" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-<a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/8-JSON_Schema_in_Practice_3/8-JSON-Schema-3.mp4">Click here if YouTube does not work go to our GitHub.</a>  
+If YouTube does not work, <a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/8-JSON_Schema_in_Practice_3/8-JSON-Schema-3.mp4">click here to watch from our GitHub repository.</a>  
 
 <br />
 <br />
@@ -57,10 +57,12 @@ However, numerous other validators exist. For further information, you can check
 
 ## Basic Validation Flow
 
-This is the basic validation flow that all libraries follow.
+[Figure 1](#fig-basic-validation-flow) shows the basic validation flow that all libraries follow.
 The library takes a schema for your JSON data and validates your data according to the schema. Outputs the validation result as a boolean.
 
-![basic validation flow](/img/8-JSON-Schema-3/basic-validation.png)
+<figure id="fig-basic-validation-flow">
+<img src="/img/8-JSON-Schema-3/basic-validation.png" alt="Basic Validation Flow" />
+<figcaption><strong>Figure 1.</strong> Basic validation flow.</figcaption> </figure>
 
 ## Javascript AJV
 

Tutorials/whatiswot/website/docs/preliminary/json-schema/practice.md

@@ -6,7 +6,7 @@ sidebar_label: JSON Schema in Practice
 
 <iframe width="100%" height="400" src="https://www.youtube.com/embed/c_gD0hYaavA?si=bPp5w0o7YIXvjZ1G" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-<a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/6-JSON_Schema_in_Practice/6-JSON-Schema-in-Practice.mp4">Click here if YouTube does not work go to our GitHub.</a>  
+If YouTube does not work, <a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/6-JSON_Schema_in_Practice/6-JSON-Schema-in-Practice.mp4">click here to watch from our GitHub repository.</a>  
 
 <br />
 <br />

Tutorials/whatiswot/website/docs/preliminary/json/intro.md

@@ -6,7 +6,7 @@ sidebar_label: Introduction
 
 <iframe width="100%" height="400" src="https://www.youtube.com/embed/7wzzwdrGFZw?si=mpDrp9FKdNywXDFf" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-<a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/3-JSON/3-JSON.mp4">Click here if YouTube does not work go to our GitHub.</a>  
+If YouTube does not work, <a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/3-JSON/3-JSON.mp4">click here to watch from our GitHub repository.</a>  
 
 <br />
 <br />

Tutorials/whatiswot/website/docs/preliminary/json/practice.md

@@ -6,7 +6,7 @@ sidebar_label: JSON in Practice
 
 <iframe width="100%" height="400" src="https://www.youtube.com/embed/bfvo4DAZG78?si=3NvJK6TDwLv82K3t" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-<a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/4-JSON_in_Practice/4-JSON_in_Practice.mp4">Click here if YouTube does not work go to our GitHub.</a>  
+If YouTube does not work, <a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/4-JSON_in_Practice/4-JSON_in_Practice.mp4">click here to watch from our GitHub repository.</a>  
 
 <br />
 <br />
@@ -28,7 +28,10 @@ Accepted types:
 - Boolean
 - Null
 
-![json array](/img/4-JSON-In-Practice/json-array.png)
+<figure id="fig-json-array">
+  <img src="/img/4-JSON-In-Practice/json-array.png" alt="Example of a JSON array" />
+  <figcaption><strong>Figure 1.</strong> Example of a JSON array.</figcaption>
+</figure>
 
 ### Nested objects
 
@@ -37,11 +40,17 @@ Nested objects are allowed in JSON. The “measurement” keyword is an example
 Objects start and end with curly brackets. We are essentially defining keywords and mapping these keywords to values.
 In this example, we define the name and value pairs to describe the data sent by sensors.
 
-![nested object](/img/4-JSON-In-Practice/nested-object.png)
+<figure id="fig-nested-object">
+  <img src="/img/4-JSON-In-Practice/nested-object.png" alt="Example of a nested JSON object" />
+  <figcaption><strong>Figure 2.</strong> Example of a nested JSON object.</figcaption>
+</figure>
 
 Here is a JSON array in which all of its items are JSON objects:
 
-![json object array](/img/4-JSON-In-Practice/json-object-array.png)
+<figure id="fig-json-object-array">
+  <img src="/img/4-JSON-In-Practice/json-object-array.png" alt="JSON array containing multiple JSON objects" />
+  <figcaption><strong>Figure 3.</strong> JSON array containing multiple JSON objects.</figcaption>
+</figure>
 
 ## Common Mistakes
 
@@ -78,13 +87,19 @@ We should always pay attention to the type we want to use and use quotation mark
 
 Putting comments inside JSON documents is not valid in contrast to most of the programming languages.
 
-![comment](/img/4-JSON-In-Practice/comment.png)
+<figure id="fig-json-comment">
+  <img src="/img/4-JSON-In-Practice/comment.png" alt="Invalid JSON example showing a comment" />
+  <figcaption><strong>Figure 4.</strong> Invalid JSON comment.</figcaption>
+</figure>
 
 ### Trailing Commas
 
-Commas should not be used at the final name-value pair - that is why the left example is not valid. This is more difficult to see if you are using it inside of a Javascript editor rather than a JSON editor.
+Commas should not be used at the final name-value pair - that is why the left example of [Figure 5](#fig-json-js) is not valid. This is more difficult to see if you are using it inside of a Javascript editor rather than a JSON editor.
 
-![json js](/img/4-JSON-In-Practice/json-js.png)
+<figure id="fig-json-js">
+  <img src="/img/4-JSON-In-Practice/json-js.png" alt="Trailing comma example in JSON vs JavaScript" />
+  <figcaption><strong>Figure 5.</strong> Trailing comma example in JSON vs JavaScript.</figcaption>
+</figure>
 
 ### Programming Language Syntax
 

Tutorials/whatiswot/website/docs/preliminary/osi-layers.md

@@ -6,7 +6,7 @@ sidebar_label: OSI Layers and Network Topologies
 
 <iframe width="100%" height="400" src="https://www.youtube.com/embed/QMNkZidA3UY?si=aB2BfW7BFBmAy34F" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-<a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/9-OSI_Layers/9-OSI-Layers.mp4">Click here if YouTube does not work go to our GitHub.</a>  
+If YouTube does not work, <a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/9-OSI_Layers/9-OSI-Layers.mp4">click here to watch from our GitHub repository.</a>  
 
 <br />
 <br />
@@ -76,7 +76,8 @@ Performing this, we were able to send the temperature data.
 
 In order for the thermometer to receive the data, it has to go through all the OSI layers but in reverse order. At the end of the process, we can observe the temperature change on the indicator.
 
-![layers](/img/tutorial/OSI-Layers/layers.png)
+<figure id="fig-osi-layers-summary">
+<img src="/img/tutorial/OSI-Layers/layers.png" alt="OSI layers overview from application to physical layer" /> <figcaption><strong>Figure 1.</strong> Summary of OSI layers.</figcaption></figure>
 
 ## Different Network Topologies
 
@@ -90,9 +91,11 @@ In all of these models, the underlying network technology remains largely consis
 
 ### Client-Server Model
 
-One of the most widely used topologies is the Client-Server Model. It consists of one server and one or more clients. In this model, the server is reactive, waiting for requests and responding to clients. Clients, on the other hand, are proactive in initiating requests.
+One of the most widely used topologies is the Client-Server Model shown in [Figure 2](#fig-server-client-model). It consists of one server and one or more clients. In this model, the server is reactive, waiting for requests and responding to clients. Clients, on the other hand, are proactive in initiating requests.
 
-![server-client-model](/img/9-OSI-Layers/server-client-model.png)
+<figure id="fig-server-client-model">
+<img src="/img/9-OSI-Layers/server-client-model.png" alt="Client-Server Model" />
+<figcaption><strong>Figure 2.</strong> Client–Server Model.</figcaption> </figure>
 
 Common protocols used in the Server-Client Model include HTTP, WebSocket, and CoAP.
 
@@ -102,7 +105,9 @@ If server and client are very tightly coupled, it is very hard one to evolve ind
 
 The Broker-Client Model is another significant topology. In this model, multiple clients connect to a central broker. While it's often referred to as Publisher-Subscriber, the term Broker-Client is more precise as PubSub can exist without a broker.
 
-![broker-client-model](/img/9-OSI-Layers/broker-client-model.png)
+<figure id="fig-broker-client-model">
+<img src="/img/9-OSI-Layers/broker-client-model.png" alt="Broker-Client Model" />
+<figcaption><strong>Figure 3.</strong> Broker–Client Model.</figcaption> </figure>
 
 The broker does not contain any application logic, it is simply a router that receives messages and sends them to clients that are listening.
 
@@ -112,8 +117,10 @@ Alternatively, multiple clients can send data to the broker, which then distribu
 
 ### Peer-to-Peer Model
 
-Lastly, we have the Peer-to-Peer Model, a true distributed system where there's no central point to retrieve data from. Each node in this model has equal functionality.
+Lastly, we have the Peer-to-Peer Model, a true distributed system where there's no central point to retrieve data from. As seen in [Figure 4](#fig-peer-to-peer-model), each node in this model has equal functionality.
 
 Examples of this model include BitTorrent and Bitcoin.
 
-![peer-to-peer-model](/img/9-OSI-Layers/peer-to-peer-model.png)
+<figure id="fig-peer-to-peer-model">
+<img src="/img/9-OSI-Layers/peer-to-peer-model.png" alt="Peer-to-peer topology" />
+<figcaption><strong>Figure 4.</strong> Peer-to-Peer Model.</figcaption> </figure>

Tutorials/whatiswot/website/docs/preliminary/payloads.md

@@ -6,7 +6,7 @@ sidebar_label: Payloads and Headers
 
 <iframe width="100%" height="400" src="https://www.youtube.com/embed/uooaqTpNtNw?si=vCoRygpQYoy3CXBe" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-<a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/2-Payloads_and_Headers/2-Payloads_and_Headers.mp4">Click here if YouTube does not work go to our GitHub.</a>  
+If YouTube does not work, <a href = "https://github.com/w3c/wot-cg/blob/main/Tutorials/whatiswot/2-Payloads_and_Headers/2-Payloads_and_Headers.mp4">click here to watch from our GitHub repository.</a>  
 
 
 <br />
@@ -18,7 +18,10 @@ This is an introductory series that presents technologies and standards relevant
 
 In the Web of Things, smart devices typically exchange data with each other. Such data is sent via payloads, therefore it is essential to understand what payloads are and the headers that describe them. Thus, in this section, we will cover the topics of headers and the different types of payloads - including JSON, the most used one in the scope of WoT, and its importance.
 
-![payloads and headers](/img/tutorial/Payloads-And-Headers/payloadsandheaders.png)
+<figure id="fig-payloads-headers-overview">
+  <img src="/img/tutorial/Payloads-And-Headers/payloadsandheaders.png" alt="Relationship between payloads and headers" />
+  <figcaption><strong>Figure 1.</strong> Relationship between payloads and headers.</figcaption>
+</figure>
 
 ## What is a payload?
 
@@ -30,25 +33,34 @@ In computing, the payload is the part of transmitted data that is the actual int
 
 The header is part of a message that can and should be understood by the protocol stack. All the information that the payload should not contain, goes to the header.
 
-> Let's go back to our truck example. In that example, the header would be the label on the goods - indicating where they are being transported, what they are and etc.
+> Let's go back to our truck example. As seen in [Figure 2](#fig-truck-example), the header would be the label on the goods - indicating where they are being transported, what they are and etc.
 
-![truck with parcels example](/img/tutorial/Payloads-And-Headers/truck.png)
+<figure id="fig-truck-example">
+  <img src="/img/tutorial/Payloads-And-Headers/truck.png" alt="Truck and parcel header analogy" />
+  <figcaption><strong>Figure 2.</strong> Analogy showing headers as labels on transported goods.</figcaption>
+</figure>
 
 ## Header Example
 
 This is what an HTTP header can look like. A header can contain information like request context, response context, status and it can indicate payload type.
 
-![http header example](/img/tutorial/Payloads-And-Headers/httpheader.png)
+<figure id="fig-http-header-example">
+  <img src="/img/tutorial/Payloads-And-Headers/httpheader.png" alt="Example contents of an HTTP header" />
+  <figcaption><strong>Figure 3.</strong> Example contents of an HTTP header.</figcaption>
+</figure>
 
 ## Payload Types
 
 There are different payload types: JSON, XML, CBOR, text and audio to name a few.
 
 So let us show you an example of a **JSON payload**. 
 
-![json payload example](/img/tutorial/Payloads-And-Headers/jsonexample.png)
+<figure id="fig-json-payload-example">
+  <img src="/img/tutorial/Payloads-And-Headers/jsonexample.png" alt="Example of a JSON payload with sensor values" />
+  <figcaption><strong>Figure 4.</strong> Example of a JSON payload used by a temperature sensor.</figcaption>
+</figure>
 
-For this example we will take a look at a temperature sensor. The diagram helps to illustrate the payloads and their relationship to the sensor. The temperature payload is a single number and is being sent from the sensor. The configuration payload is a JSON object consisting of key/value pairs desiredUnit and updateInterval and is sent to the sensor.
+For this example we will take a look at a temperature sensor. [Figure 4](#fig-json-payload-example) helps to illustrate the payloads and their relationship to the sensor. The temperature payload is a single number and is being sent from the sensor. The configuration payload is a JSON object consisting of key/value pairs desiredUnit and updateInterval and is sent to the sensor.
 
 Temparature payload: