[IMP] Time Off: Updating Allocations

closes odoo/documentation#14321

X-original-commit: 71331268f2
Signed-off-by: Lara Martini (larm) <larm@odoo.com>

content/applications/hr/time_off/allocations.rst

@@ -2,6 +2,9 @@
 Allocations
 ===========
 
+Allocations are amounts of time off given to employees, either granted immediately or earned as the
+employee works, through an accrual plan.
+
 Once :ref:`time off types <time_off/time-off-types>` and :ref:`accrual plans
 <time_off/accrual-plans>` have been configured, the next step is to *allocate*, or give, time off to
 employees.
@@ -26,15 +29,17 @@ Click :guilabel:`New` to allocate time off, and a blank :guilabel:`Allocation` f
 After entering a name for the allocation on the first blank field of the form, enter the following
 information:
 
+- :guilabel:`Name`: Enter a name for the allocation, typically containing the type of time off, and
+  the period of time it is available (example: `Annual Vacation Time Off - 2025`).
 - :guilabel:`Time Off Type`: Using the drop-down menu, select the type of time off that is being
   allocated to the employees.
-- :guilabel:`Allocation Type`: Select either :guilabel:`Regular Allocation` or :guilabel:`Accrual
-  Allocation`. If the allocation is **not** based on an :ref:`accrual plan
-  <time_off/accrual-plans>`, select :guilabel:`Regular Allocation`.
+- :guilabel:`Allocation Type`: Select how the allocation is granted. Choose :guilabel:`Regular
+  Allocation` if the time off is given immediately, or :guilabel:`Accrual Allocation` if the time
+  off is earned through an :ref:`accrual plan <time_off/accrual-plans>`.
 - :guilabel:`Accrual Plan`: If :guilabel:`Accrual Allocation` is selected for the
   :guilabel:`Allocation Type`, the :guilabel:`Accrual Plan` field appears. Using the drop-down menu,
-  select the accrual plan with which the allocation is associated. An accrual plan **must** be
-  selected for an :guilabel:`Accrual Allocation`.
+  select the accrual plan associated with the allocation. An accrual plan is **required** when using
+  the :guilabel:`Accrual Allocation` type.
 - :guilabel:`Validity Period/Start Date`: If :guilabel:`Regular Allocation` is selected for the
   :guilabel:`Allocation Type`, this field is labeled :guilabel:`Validity Period`. If
   :guilabel:`Accrual Allocation` is selected for the :guilabel:`Allocation Type`, this field is
@@ -45,37 +50,14 @@ information:
   allocation, and click on the date to select it.
 
   If the allocation expires, select the expiration date in the next date field. If the time off does
-  *not* expire, leave the second date field blank. :guilabel:`No Limit` appears in the field if no
-  date is selected.
+  *not* expire, leave the second date field blank.
 
   If :guilabel:`Accrual Allocation` is selected for the :guilabel:`Allocation Type`, this second
   field is labeled :guilabel:`Run until`.
-
-  .. important::
-     If the :guilabel:`Start Date` entered is in the middle of a period of time, such as the middle
-     of the month, Odoo applies the allocation to the beginning or end of the period, depending on
-     the *Accrued Gain Time* entered on the :ref:`accrual plan <time_off/accrual-plans>` (either *At
-     the start of the accrual period*, or *At the end of the accrual period*) instead of the
-     specific date entered.
-
-     For example, an allocation is created, and references an accrual plan that grants time *At the
-     start of the accrual period*, monthly, on the first of the month.
-
-     On the allocation form, the :guilabel:`Allocation Type` is set to :guilabel:`Accrual
-     Allocation`, and the :guilabel:`Start Date` entered is `06/16/24`.
-
-     Odoo's **Time Off** app retroactively applies the allocation to the beginning of the time
-     period entered in the :guilabel:`Start Date`.
-
-     Therefore, this allocation accrues time from `06/01/24`, rather than `06/16/24`.
-
-     Additionally, if on the accrual form, the allocation references an accrual plan that grants
-     time *`At the end of the accrual period*, the allocation accrues time from `7/01/24` rather
-     than `6/18/24`.
-
 - :guilabel:`Allocation`: Enter the amount of time that is being allocated to the employees. This
   field displays the time in either :guilabel:`Hours` or :guilabel:`Days`, depending on how the
   selected :ref:`Time Off Type <time_off/time-off-types>` is configured.
+- :guilabel:`Employee`: Using the drop-down menu, select the employee being allocated the time off.
 - :guilabel:`Add a reason...`: If any description or note is necessary to explain the time off
   allocation, enter it in this field at the bottom of the form.
 
@@ -83,8 +65,24 @@ information:
    :alt: A new allocation form with all the fields filled out for the annual two week vacation
          granted to all employees.
 
-Multiple Allocations
---------------------
+Accrual start date behavior
+---------------------------
+
+If the :guilabel:`Start Date` is in the middle of an accrual period, Odoo adjusts it to the start or
+end of that period based on the *Accrued Gain Time* entered on the :ref:`accrual plan
+<time_off/accrual-plans>`.
+
+.. example::
+   - *At the start of the accrual period*: A :guilabel:`Start Date` of `06/16/25` applies from
+     `06/01/25`
+   - *At the end of the accrual period*: A :guilabel:`Start Date` of `06/18/25` applies from
+     `07/01/25`
+
+Automatic adjustments on the start date to either the begining or end of an accural period ensures
+accruals align with the defined period boundaries, rather than the exact date entered.
+
+Multiple requests
+-----------------
 
 When allocating time off, it is common to allocate time to several employees at once. This is done
 using the :guilabel:`Multiple Requests` feature.
@@ -94,10 +92,10 @@ app --> Management --> Allocations`. Then, click the :icon:`fa-gear` :guilabel:`
 the upper-left corner, then click :icon:`fa-users` :guilabel:`Multiple Requests`. This reveals a
 :guilabel:`Multiple Requests` pop-up window.
 
-This form is identical to the :guilabel:`Allocation` form, with an additional :guilabel:`Mode`
-field. The :guilabel:`Mode` field determines how multiple employees are selected.
+This form is identical to the :ref:`Allocation form <time_off/allocation-form>`, with an additional
+:guilabel:`Mode` field. The :guilabel:`Mode` field determines how multiple employees are selected.
 
-Using the drop-down menu, select one of the following :guilabel:`Modes`:
+Using the drop-down menu, select a :guilabel:`Mode` from one of the following options:
 
 - :guilabel:`By Employee`: This option allows for the selection of multiple individual employees
   that are unrelated in terms of department, company, or tags. Selecting this reveals an
@@ -126,9 +124,31 @@ desired.
 Fill out the remainder of the :ref:`Multiple Requests form <time_off/allocation-form>`, then click
 :guilabel:`Create Allocations` when done.
 
-.. image:: allocations/multiple-requests.png
-   :alt: An allocation request form filled out for sick time for all employees within the sales
-         department.
+.. example::
+   A company hosts an annual picnic, including a raffle. There are five raffle prizes for a free
+   vacation day, which must be redeemed by the end of the year. The winners of this raffle all have
+   the tag `Raffle Winner - 2025 Employee Picnic Prize` added to their employee profiles.
+
+   The time off officer creates multiple allocations, and configures the :ref:`Multiple Requests
+   form <time_off/allocation-form>` as follows:
+
+   The name for the allocation is :guilabel:`Vacation Day - Raffle Prize - 2025 Picnic`. The
+   :guilabel:`Mode` is set to :guilabel:`By Employee Tag`, and the :guilabel:`Tag` identified is
+   :guilabel:`Raffle Winner - 2025 Employee Picnic Prize`.
+
+   The :guilabel:`Time Off Type` is set to :guilabel:`Vacation Time Off`, with the
+   :guilabel:`Allocation Type` set to :guilabel:`Regular Allocaiton`, since the time off is given up
+   front, and is not *earned*.
+
+   The :guilabel:`Validity Period` is set to :guilabel:`07/18/2025` :icon:`oi-arrow-right`
+   :guilabel:`12/31/2025`, since the compnay picnic was that day, and the earned vacation day
+   expires at the end of the year.
+
+   The :guilabel:`Allocation` is set to :guilabel:`1.00 Days`, and `A bonus vacation day won at the
+   annual Company Picnic.` appears in the details at the bottom.
+
+   .. image:: allocations/multiple-requests.png
+      :alt: An allocation request form filled out for a bonus vacation day for raffle winners.
 
 .. _time_off/request-allocation:
 
@@ -146,13 +166,15 @@ list view. Both buttons open a new allocation request form.
 .. note::
    Both options open a new allocation request form, but when requested from the
    :guilabel:`Dashboard`, the form appears in a pop-up window, and the *Validity Period* field does
-   **not** appear. When requested from the :guilabel:`My Allocations` list view, the screen
-   navigates to a new allocation request page, instead of presenting a pop-up window.
+   **not** appear.
+
+   When requested from the :guilabel:`My Allocations` list view, the screen navigates to a new
+   allocation request page, instead of presenting a pop-up window.
 
 Enter the following information on the new allocation request form:
 
-- :guilabel:`Time Off Type`: Select the type of time off being requested for the allocation from the
-  drop-down menu. After a selection is made, the title updates with the time off type.
+- :guilabel:`Time Off Type`: Using the drop-down menu, select the type of time off being requested
+  for the allocation. After a selection is made, the title updates with the time off type.
 - :guilabel:`Validity Period`: By default, the current date populates this field, and it is **not**
   able to be modified. This field **only** appears when requesting an allocation from the
   :guilabel:`My Allocations` view (:menuselection:`Time Off --> My Time --> My Allocations`).
@@ -167,8 +189,7 @@ If the request was created from the :guilabel:`Dashboard`, click the :guilabel:`
 on the :guilabel:`New Allocation` pop-up window to save the information and submit the request.
 
 If the form was completed from the :guilabel:`My Allocations` list view, the information is
-automatically saved as it is entered. However, the form can be saved manually at any time by
-clicking the :icon:`fa-cloud-upload` :guilabel:`(cloud upload)` icon.
+automatically saved as it is entered.
 
 .. image:: allocations/allocation-request.png
    :alt: An allocation request form filled out for an employee requesting an additional week of