docs: enhance documentation clarity and examples in Nada-by-example

docs/nada-by-example/addition.md

@@ -1,5 +1,7 @@
 # Addition
 
+This example demonstrates how to perform basic addition operations in Nada. It shows a simple implementation of adding two numbers together, showcasing the fundamental arithmetic capabilities of the Nada language.
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import TestProgram from '@site/src/components/TestProgram/index';
@@ -19,4 +21,4 @@ https://github.com/NillionNetwork/nada-by-example/blob/main/tests/addition_test.
 </TabItem>
 </Tabs>
 
-<TestProgram programName="addition"/>
+<TestProgram programName="addition"/>

docs/nada-by-example/arg-max.md

@@ -4,7 +4,7 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import TestProgram from '@site/src/components/TestProgram/index';
 
-Argmax is a data wrangling operation to find the index of the maximum value in a list of values.
+The arg max (argument of the maximum) operation finds the index of the maximum value in a sequence of numbers. For example, in the sequence [3, 1, 4, 1, 5], the arg max would return 4 because the maximum value (5) is at index 4.
 
 <Tabs>
 

docs/nada-by-example/cardio-risk.md

@@ -4,7 +4,12 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import TestProgram from '@site/src/components/TestProgram/index';
 
-The cardio risk example program returns a risk score that depends on private checks.
+This example demonstrates a privacy-preserving cardiovascular risk assessment program. It calculates a risk score based on several private health metrics (such as blood pressure, cholesterol levels, etc.) without exposing the individual values. The program uses secure computation to protect sensitive medical data while still providing meaningful risk assessment results.
+
+The risk score is computed on a scale from 0 to 100, where:
+- 0-20: Low risk
+- 21-50: Moderate risk
+- 51-100: High risk
 
 <Tabs>
 
@@ -39,4 +44,4 @@ https://github.com/NillionNetwork/nada-by-example/blob/main/tests/cardio_risk_3_
 </TabItem>
 </Tabs>
 
-<TestProgram programName="cardio_risk" testFileName="cardio_risk_0_test"/>
+<TestProgram programName="cardio_risk" testFileName="cardio_risk_0_test"/>

docs/nada-by-example/comparison.md

@@ -4,7 +4,12 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import TestProgram from '@site/src/components/TestProgram/index';
 
+Nada supports standard comparison operations for comparing numerical values. These operators return boolean values (true/false) and can be used in conditional statements or calculations. Each comparison is performed securely, maintaining the privacy of the operands.
+
+The following comparison operators are available:
+
 ## Less than `<`
+Returns `true` if the first value is less than the second value.
 
 <Tabs>
 
@@ -24,6 +29,7 @@ https://github.com/NillionNetwork/nada-by-example/blob/main/tests/comparison_lt_
 <TestProgram programName="comparison_lt"/>
 
 ## Less than or equal to `<=`
+Returns `true` if the first value is less than or equal to the second value.
 
 <Tabs>
 
@@ -43,6 +49,7 @@ https://github.com/NillionNetwork/nada-by-example/blob/main/tests/comparison_lte
 <TestProgram programName="comparison_lte"/>
 
 ## Greater than `>`
+Returns `true` if the first value is greater than the second value.
 
 <Tabs>
 
@@ -62,6 +69,7 @@ https://github.com/NillionNetwork/nada-by-example/blob/main/tests/comparison_gt_
 <TestProgram programName="comparison_gt"/>
 
 ## Greater than or equal to `>=`
+Returns `true` if the first value is greater than or equal to the second value.
 
 <Tabs>