diff --git a/CarProject/Air.mo b/CarProject/Air.mo
index c3333ff41388628b7405b3fbcd094d2273ae04dc..8bc2c14a6509d21ae3e90438401ab8d1cd112782 100644
--- a/CarProject/Air.mo
+++ b/CarProject/Air.mo
@@ -1,6 +1,6 @@
 within CarProject;
 
-model Air
+model Air "Air moving a constant speed + sinus perturbation"
   parameter Velocity v(displayUnit="km/h") "reverse wind speed";
   parameter Velocity v_pert(displayUnit="km/h") "wind speed periodic perturbation";
   Force f "total aerdynamic drag force";
diff --git a/CarProject/Car.mo b/CarProject/Car.mo
index 5b8a93defa122410c3c05b1c531bc5a41708ae32..736c0905addac34be7af24dd86192bbcd3397ca6 100644
--- a/CarProject/Car.mo
+++ b/CarProject/Car.mo
@@ -1,6 +1,6 @@
 within CarProject;
 
-model Car
+model Car "Car with a speed control"
   Position s "car position";
   Velocity v(displayUnit = "km/h") "car velocity";
   parameter Modelica.SIunits.Mass m_car=1e3 "car mass";
@@ -11,7 +11,7 @@ model Car
     Placement(visible = true, transformation(origin = {30, 0}, extent = {{-10, -10}, {10, 10}}, rotation = 0)));
   CarProject.Components.Controller controller1 "contrôleur de vitesse" annotation(
     Placement(visible = true, transformation(origin = {-50, 0}, extent = {{-10, -10}, {10, 10}}, rotation = 0)));
-  CarProject.Components.Engine engine1 annotation(
+  CarProject.Components.Engine engine annotation(
     Placement(visible = true, transformation(origin = {-10, 0}, extent = {{-10, -10}, {10, 10}}, rotation = 0)));
   Modelica.Mechanics.Translational.Sensors.SpeedSensor speedSensor1 annotation(
     Placement(visible = true, transformation(origin = {30, -30}, extent = {{-10, -10}, {10, 10}}, rotation = 0)));
@@ -32,16 +32,16 @@ equation
     Line(points = {{20, 0}, {20, -30}}, color = {0, 127, 0}));
   connect(speedSensor1.v, controller1.v) annotation(
     Line(points = {{41, -30}, {74, -30}, {74, -50}, {-72, -50}, {-72, -4}, {-62, -4}}, color = {0, 0, 127}));
-  connect(engine1.flange_b, mass1.flange_a) annotation(
+  connect(engine.flange_b, mass1.flange_a) annotation(
     Line(points = {{0, 0}, {20, 0}}, color = {0, 127, 0}));
-  connect(engine1.flange_a, flange_road) annotation(
+  connect(engine.flange_a, flange_road) annotation(
     Line(points = {{-10, -10}, {-10, -30}}, color = {0, 127, 0}));
-  connect(controller1.f, engine1.f) annotation(
+  connect(controller1.f, engine.f) annotation(
     Line(points = {{-38, 0}, {-22, 0}}, color = {0, 0, 127}));
   /*define car position*/
   s = mass1.s;
   v = mass1.v;
   annotation(
-    Icon(graphics = {Polygon(fillColor = {239, 41, 41}, fillPattern = FillPattern.Solid, points = {{-100, -60}, {100, -60}, {100, 0}, {40, 60}, {-80, 60}, {-100, 0}, {-100, -60}}), Ellipse(origin = {-50, -70}, fillColor = {136, 138, 133}, fillPattern = FillPattern.Solid, extent = {{-30, -30}, {30, 30}}, endAngle = 360), Ellipse(origin = {50, -70}, fillColor = {136, 138, 133}, fillPattern = FillPattern.Solid, extent = {{-30, -30}, {30, 30}}, endAngle = 360), Text(origin = {0, 120}, extent = {{-100, 20}, {100, -20}}, textString = "%name"), Text(origin = {-3, -9}, extent = {{-97, 29}, {103, -31}}, textString = "m=%m_car"), Line(origin = {60, 70}, points = {{20, 0}, {-20, 0}}, color = {79, 138, 226}, thickness = 1, arrow = {Arrow.None, Arrow.Open})}, coordinateSystem(initialScale = 0.1)),
+    Icon(graphics = {Polygon(fillColor = {239, 41, 41}, fillPattern = FillPattern.Solid, points = {{-100, -60}, {100, -60}, {100, 0}, {40, 60}, {-80, 60}, {-100, 0}, {-100, -60}}), Ellipse(origin = {-50, -70}, fillColor = {136, 138, 133}, fillPattern = FillPattern.Solid, extent = {{-30, -30}, {30, 30}}, endAngle = 360), Ellipse(origin = {50, -70}, fillColor = {136, 138, 133}, fillPattern = FillPattern.Solid, extent = {{-30, -30}, {30, 30}}, endAngle = 360), Text(origin = {0, 80}, lineColor = {0, 67, 168}, fillColor = {0, 67, 168}, extent = {{-100, 20}, {40, -20}}, textString = "%name"), Text(origin = {-3, -9}, extent = {{-97, 29}, {103, -31}}, textString = "m=%m_car"), Line(origin = {60, 70}, points = {{20, 0}, {-20, 0}}, color = {79, 138, 226}, thickness = 1, arrow = {Arrow.None, Arrow.Open})}, coordinateSystem(initialScale = 0.1)),
     Diagram(graphics = {Text(origin = {51, 53}, extent = {{-33, 5}, {33, -5}}, textString = "frottement de l'air")}));
 end Car;
\ No newline at end of file
diff --git a/CarProject/CarTest.mo b/CarProject/CarTest.mo
index d8edfa6a1b0febfb512fd3cc9e7cfb40ea78332c..0bfb14e8246faab402c8fd0b916b14309e13b058 100644
--- a/CarProject/CarTest.mo
+++ b/CarProject/CarTest.mo
@@ -1,21 +1,22 @@
 within CarProject;
 
-model CarTest
+model CarTest "Demo for the Car"
   extends Modelica.Icons.Example;
-  CarProject.Car car1(m_car = 1e3, v_sp = 27.7778)  annotation(
+  CarProject.Car car(m_car = 1e3, v_sp = 27.7778)  annotation(
     Placement(visible = true, transformation(origin = {0, 0}, extent = {{-20, -20}, {20, 20}}, rotation = 0)));
   CarProject.Air air1(v = 11.1111, v_pert = 5.55556)  annotation(
     Placement(visible = true, transformation(origin = {70, 10}, extent = {{-10, -10}, {10, 10}}, rotation = 0)));
   CarProject.Road road1 annotation(
     Placement(visible = true, transformation(origin = {10, -50}, extent = {{-10, -10}, {10, 10}}, rotation = 0)));
 equation
-  connect(air1.flange_b, car1.flange_air) annotation(
+  connect(air1.flange_b, car.flange_air) annotation(
     Line(points = {{60, 10}, {18, 10}, {18, 14}, {18, 14}}, color = {0, 127, 0}));
   connect(air1.flange_a, road1.flange) annotation(
     Line(points = {{70, 0}, {70, -49}, {10, -49}}, color = {0, 127, 0}));
-  connect(car1.flange_road, road1.flange) annotation(
+  connect(car.flange_road, road1.flange) annotation(
     Line(points = {{10, -20}, {10, -49}}, color = {0, 127, 0}));
+
 annotation(
     experiment(StopTime=180),
-    Diagram(graphics = {Text(origin = {0, 80}, extent = {{-100, 20}, {100, -20}}, textString = "Car test on the road")}));
+    Diagram(graphics = {Text(origin = {0, 80}, extent = {{-100, 20}, {100, -20}}, textString = "Car test on the road"), Text(origin = {1, -81}, extent = {{-99, 15}, {99, -15}}, textString = "observe car.v and car.v_sp", textStyle = {TextStyle.Italic})}, coordinateSystem(initialScale = 0.1)));
     end CarTest;
\ No newline at end of file
diff --git a/CarProject/Components/Controller.mo b/CarProject/Components/Controller.mo
index e40e978bdbc71fbc3521fe0644f19f47b9486318..460c601830f9973c85ded148d0db73575c3ce919 100644
--- a/CarProject/Components/Controller.mo
+++ b/CarProject/Components/Controller.mo
@@ -1,6 +1,6 @@
 within CarProject.Components;
 
-model Controller
+model Controller "Speed controller"
   parameter Modelica.SIunits.Time tc = 5 "expected closed loop time constant (cf. Skogestad 2003)";
   Modelica.Blocks.Interfaces.RealOutput f "force control" annotation(
     Placement(visible = true, transformation(origin = {106, 0}, extent = {{-10, -10}, {10, 10}}, rotation = 0), iconTransformation(origin = {110, 0}, extent = {{-10, -10}, {10, 10}}, rotation = 0)));
diff --git a/CarProject/Velocity.bak-mo b/CarProject/Velocity.bak-mo
deleted file mode 100644
index 40d13c4613bf1b74ef3f2c74f9a1da1517885e96..0000000000000000000000000000000000000000
--- a/CarProject/Velocity.bak-mo
+++ /dev/null
@@ -1,3 +0,0 @@
-within CarProject;
-
-type Velocity = Modelica.SIunits.Velocity(displayUnit = "km/h");
\ No newline at end of file
diff --git a/README.md b/README.md
index aa2a6d226b04bed11e32b74c4928f95100f073a3..f77f67112a725fd202e7c6f1bba9c697cfd8436a 100644
--- a/README.md
+++ b/README.md
@@ -2,3 +2,16 @@
 
 This project is a minimal simulation of car on a road.
 It is intended as a generic example for all Modelica Modeling projects
+
+## Checklist
+
+* The package structure is reasonably "tidy"
+* All models have a description string
+* All parameters and variables have a physical unit and, when applicable, 
+  a reasonable displayUnit
+  
+Simulation models:
+
+* It is clear which models are supposed to be simulated
+  (e.g. by extending from `Modelica.Icons.Example`)
+* A default simulation duration is set (`annotation(experiment(StopTime=180));`)