Update documentation of CCS example

docs/ccs_example.md

@@ -5,6 +5,78 @@
 
 ## Child Care Subsidy Example
 
+The Child Care Subsidy (CCS) is a financial assistance to help families with the cost of
+child care. For example, the amount given by the Australian Government depends on the
+[family circumstances][australian-conditions]. In this example, we explore different
+criteria to define a fair distribution of the child care subsidy. Each criterion is defined
+by a pipeline, as described in the next sections.
+
+This project includes an **executable example** of Child Care Subsidy pipelines. The script
+`makeall.sh` creates the file `tiles`, which is an executable JAR file that can be directly
+executed in Linux. Its input is a [YAML][yaml] configuration file, like the
+[configuration file][test-yaml-conf] provided for the unit tests. A simplified version is
+shown below.
+
+```yaml
+---
+
+
+## Tiles (https://julianmendez.github.io/tiles/)
+
+
+## Actors for this scenario
+actors:
+  family A: .
+
+
+## Resources for this scenario
+resources:
+  subsidy 100: .
+
+
+## Number of children in each family.
+actor_children:
+  family A: 2
+
+
+## Number of guardians in each family.
+actor_adults:
+  family A: 2
+
+
+## Total income in each family.
+actor_income:
+  family A: 2000
+
+
+## The value of each resource.
+resource_value:
+  subsidy 100: 100
+
+
+## The resources received by the family, checked by the pipeline.
+outcome:
+  family A: subsidy 100
+
+
+## Pipelines that can test the provided data.
+pipelines:
+  CcsNoSubsidyPipeline: .
+  CcsPerChildPipeline: .
+  CcsPerFamilyPipeline: .
+  CcsSingleGuardianPipeline: .
+```
+
+This example is modeled with Tiles, where each actor is a family. The families (`actors`)
+and subsidies (`resources`) have identifiers. In addition, the resources have some value (
+`resource_value`). The assignments (`outcome`) relate actors with resources.  Some of the
+properties that each family has are: number of adults in the family (`actor_adults`) and
+number of children in the family (`actor_children`). All the pipelines to be tested have
+their own section (`pipelines`).
+
+
+### Tiles used
+
 | Tile                                                | Class                                    |
 |:----------------------------------------------------|:-----------------------------------------|
 | all-actor <sub>*(a)*</sub>                          | [AllActorTile][AllActorTile]             |
@@ -20,7 +92,7 @@
 
 ### No Child Care Subsidy
 
-This is the [No Subsidy Pipeline][CcsNoSubsidyPipeline].
+This is the [No Subsidy Pipeline][CcsNoSubsidyPipeline]. In this case, no subsidy is given to any family.
 
 ```mermaid
 graph LR
@@ -31,7 +103,8 @@ graph LR
 
 ### Child Care Subsidy Per Child Pipeline
 
-This is the [Per Child Pipeline][CcsPerChildPipeline].
+This is the [Per Child Pipeline][CcsPerChildPipeline]. In this case, the amount of money
+given to each family depends on the number of children in the family.
 
 ```mermaid
 graph LR
@@ -45,7 +118,8 @@ graph LR
 
 ### Child Care Subsidy Per Family Pipeline
 
-This is the [Per Family Pipeline][CcsPerFamilyPipeline].
+This is the [Per Family Pipeline][CcsPerFamilyPipeline]. In this case, the amount of money
+given to each family is the same, regardless of the number of children in the family.
 
 ```mermaid
 graph LR
@@ -56,7 +130,8 @@ graph LR
 
 ### Child Card Subsidy to Single Guardian Pipeline
 
-This is the [Single Guardian Pipeline][CcsSingleGuardianPipeline].
+This is the [Single Guardian Pipeline][CcsSingleGuardianPipeline]. In this case, the subsidy
+is only granted to families having a single guardian.
 
 ```mermaid
 graph LR
@@ -70,6 +145,7 @@ graph LR
   all-satisfy-0(all-satisfy m=0) --> and
 ```
 
+[yaml]: https://yaml.org
 [AllActorTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllActorTile.soda
 [ReceivedSigmaPTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/ReceivedSigmaPTile.soda
 [AllSatisfyPTile]: https://github.com/julianmendez/tiles/blob/master/core/src/main/scala/soda/tiles/fairness/tile/AllSatisfyPTile.soda
@@ -83,6 +159,8 @@ graph LR
 [CcsNoSubsidyPipeline]: https://github.com/julianmendez/tiles/blob/master/examples/src/main/scala/soda/tiles/fairness/example/childcaresubsidy/CcsNoSubsidyPipeline.soda
 [CcsPerChildPipeline]: https://github.com/julianmendez/tiles/blob/master/examples/src/main/scala/soda/tiles/fairness/example/childcaresubsidy/CcsPerChildPipeline.soda
 [CcsPerFamilyPipeline]: https://github.com/julianmendez/tiles/blob/master/examples/src/main/scala/soda/tiles/fairness/example/childcaresubsidy/CcsPerFamilyPipeline.soda
+[test-yaml-conf]: https://github.com/julianmendez/tiles/blob/master/examples/src/test/resources/example/example0.yaml
+[australian-conditions]: https://www.servicesaustralia.gov.au/how-much-child-care-subsidy-you-can-get?context=41186
 
 <script>
   window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));