documentation for the new mechanism

skeleton for the user manual