diff --git a/docs/system-admin-guide/manage-work-packages/work-package-progress-tracking/README.md b/docs/system-admin-guide/manage-work-packages/work-package-progress-tracking/README.md index c749101a62e0..cc84f6b914a1 100644 --- a/docs/system-admin-guide/manage-work-packages/work-package-progress-tracking/README.md +++ b/docs/system-admin-guide/manage-work-packages/work-package-progress-tracking/README.md @@ -9,28 +9,36 @@ keywords: work package progress tracking, percentage complete, % complete # Manage work package progress tracking -Progress tracking is a - -Administrators will see a new page under *Administration* → *Work packages* called **Progress tracking** with three settings: +To manage the settings for progress tracking in work packages, navigate to *Administration* → *Work packages → Progress tracking*. ![Progress tracking settings under OpenProject administration](openproject_system_guide_progress_tracking_settings.png) -- **Progress calculation mode** lets you select between *work-based* and *status-based* modes. +## Progress calculation mode +*Progress calculation mode* lets you select between *work-based* and *status-based* modes. + +- **Work-based mode**: *% Complete* is either set manually or is automatically calculated based on *Work* and *Remaining work* values for that work package, both of which are then necessary to have a value for % Complete. Please refer to [progress tracking user guide](../../../user-guide/time-and-costs/progress-tracking/#work-based-progress-reporting) for more details and calculation examples. +- **Status-based mode**: you will have to define fixed % Complete values for each [work package status](../work-package-status), which will update automatically when team members update the status of their work packages. + + > [!NOTE] + > When switching progress calculation mode from one to another, you will see a warning message. + > + > - Changing progress calculation mode from work-based to status-based will result in all existing *% Complete* values to be lost and replaced with values associated with each status. Existing values for *Remaining work* may also be recalculated to reflect this change. This action is not reversible. + > + > - Changing progress calculation mode from status-based to work-based will make % Complete a non-editable field whose value is derived from Work and Remaining work. Existing values for % Complete are preserved. If values for Work and Remaining work were not present, they will be required in order to change % Complete. -- Calculation of % Complete hierarchy totals +![Warning message when changing progress calculation mode in OpenProject administration](openproject_system_guide_progress_tracking_settings_warning_message.png) - lets you pick between: +## Calculation of % Complete hierarchy totals - - Weighted by work: The total *% Complete* will be weighted against the *Work* of each work package in the hierarchy. Work packages without *Work* will be ignored (current behaviour) - - Simple average: *Work* is ignored and the total *% Complete* will be a simple average of *% Complete* values of work packages in the hierarchy +*Calculation of % Complete hierarchy totals* lets you determine how the values of the *% Complete* will be calculated in work package hierarchies. -- % Complete when status is closed +- **Weighted by work**: The total *% Complete* will be weighted against the *Work* of each work package in the hierarchy. Work packages with no *Work* values are not included into the calculation. - lets you chose what happens to +- **Simple average**: The total *% Complete* is calculated by averaging the *% Complete* values of all work packages, regardless of their *Work* values. *Work* is not factored into the calculation. - % Complete +## % Complete when status is closed - when you close a work package (even in work-based mode): +*% Complete when status is closed* lets you chose what happens to % Complete when you close a work package (even in the work-based mode). - - No change, where the value of *% Complete* will not change even when a work package is closed - - Automatically set to 100%, where a closed work package is considered complete. +- **No change** - if you select this option, the value of *% Complete* will not change even when a work package is closed. +- **Automatically set to 100%** - if you select this option, work package will be considered complete when closed. diff --git a/docs/system-admin-guide/manage-work-packages/work-package-progress-tracking/openproject_system_guide_progress_tracking_settings_warning_message.png b/docs/system-admin-guide/manage-work-packages/work-package-progress-tracking/openproject_system_guide_progress_tracking_settings_warning_message.png new file mode 100644 index 000000000000..9b3896850bb9 Binary files /dev/null and b/docs/system-admin-guide/manage-work-packages/work-package-progress-tracking/openproject_system_guide_progress_tracking_settings_warning_message.png differ diff --git a/docs/system-admin-guide/manage-work-packages/work-package-settings/openproject_system_guide_work_package_settings.png b/docs/system-admin-guide/manage-work-packages/work-package-settings/openproject_system_guide_work_package_settings.png index 6c5332a9adce..d5ca2938aec5 100644 Binary files a/docs/system-admin-guide/manage-work-packages/work-package-settings/openproject_system_guide_work_package_settings.png and b/docs/system-admin-guide/manage-work-packages/work-package-settings/openproject_system_guide_work_package_settings.png differ diff --git a/docs/user-guide/time-and-costs/progress-tracking/README.md b/docs/user-guide/time-and-costs/progress-tracking/README.md index 08ca7e770111..04be1fcdfa5c 100644 --- a/docs/user-guide/time-and-costs/progress-tracking/README.md +++ b/docs/user-guide/time-and-costs/progress-tracking/README.md @@ -57,7 +57,7 @@ OpenProject offers two modes for reporting progress: - **Status-based progress reporting** allows you to assign fixed % Complete values to statuses, and automatically derive Remaining work based on the values for Work you can enter. > [!NOTE] -> The administrator of your instance will have selected a mode for the entire instance. If you are an administrator, you can modify this by following our [admin guide on work package settings](../../../system-admin-guide/manage-work-packages/work-package-settings). +> The administrator of your instance will have selected a mode for the entire instance. If you are an administrator, you can modify this by following our [admin guide on work package settings](../../../system-admin-guide/manage-work-packages/work-package-progress-tracking). ### Work-based progress reporting @@ -65,23 +65,68 @@ In the work-based progress reporting mode % Complete can either be automati #### Manual values for % Complete -If you you prefer to enter the values for % Complete manually, you can. +If you you prefer to enter the values for % Complete manually, you can. You can do that in the table view and work package details view. Values for *Work* and *Remaining work* are not required to enter % Complete. + +> [!IMPORTANT] +> +> If you do not enter \*Work\* or \*Remaining work\*, the \*% Complete\* field will remain an independent, manually editable field and behave like it did prior to OpenProject 14.0. + +![Manually entering values for % Complete in OpenProject](openproject_user_guide_percentage_complete_manual.png) + + #### Automatic values for % Complete +If you enter a value for *% Complete* and one other field (*Work* or *Remaining work*), the third one will automatically be derived based on the other two. This means that there can be one value (if % Complete is entered manually) or three values but never just two values. + >**% Complete** is work done (**Work** - **Remaining work**) divided by **Work**, expressed as a percentage. For example, if Work is set at 50h and Remaining work is 30h, this means that % Complete is _(50h-30h)/50h))_ = **40%**. Please note that these calculations are independent and unrelated to the value of **Spent time** (which is based on actual time logged). -This means that for a work package to have a value for % Complete, both Work and Remaining work are required to be set. To make this link clear and transparent, clicking on *Work* or *Remaining work* to modify them will display the following pop-over: +To make this link clear and transparent, clicking on *Work* or *Remaining work* to modify them will display the following pop-over: ![Work estimates and progress pop-over with work-based progress reporting](progress-popover-work-based-days.png) This allows you to edit Work or Remaining work and get a preview of the updated % Complete value before saving changes. Changing any one field will automatically update the other two. +When you add, edit, or remove a value for *Work*, *Remaining Work*, or *% Complete*, and it affects another field, a helpful message will appear explaining what has changed and why. + +![Helpful hint on progress tracking calculation in OpenProject](openproject_user_guide_percentage_complete_calculation_hint.png) + +#### Calculation logic + +**When no field is set** + +When none of the three fields (% Complete, Work, or Remaining Work) have values set, the field you fill in first will determine how the others are calculated: + +- If you enter % Complete only, no other fields will be automatically updated. Work and Remaining Work will remain empty. +- If you enter Work only, Remaining Work will automatically match the Work value, and % Complete will be set to 100%. You can manually clear these values if needed. +- If you enter Remaining Work only, Work will automatically match the Remaining Work value, and % Complete will be set to 100%. You can manually clear these values if needed. + +**When one field is set** + +When one field is already set and you enter a value in a second field, the third field will be automatically calculated: + +- If Work is already set and you enter % Complete, Remaining Work will be automatically calculated. +- If Remaining Work is already set and you enter % Complete, Work will be automatically calculated. +- If you enter Remaining Work when Work is already set (or vice versa), % Complete will be automatically calculated. + > [!NOTE] > If you enter a value for Remaining work that is higher than Work, you will see an error message telling you that this is not possible. You will have to enter a value lower than Work to be able to save the new value. -> >Additionally, the value for Remaining work cannot be removed if a value for Work exists. If you wish to unset Remaining work, you need to also unset Work. +> [!NOTE] +> **If you enter a % Complete value of 100% when Remaining work has a value**, this will also result in an error, since Remaining work must be 0h when % Complete is 100%. + +**When all values are set** + +- **Increasing Work**: When you increase the value of Work, the same amount is added to Remaining Work (since the total Work has increased). This change also updates the % Complete accordingly. +- **Decreasing Work**: + - If you decrease *Work*, *Remaining work* is lowered by the same amount: + - If you decrease *Work* by less than the current value for *Remaining work*, then *Remaining work* will be set to 0h and *% Complete* to 100% +- **Changing Remaining work updates % Complete** +- **Changing % Complete updates Remaining work** + +For more details and examples of progress tacking calculation please refer to this [blog article](https://www.openproject.org/blog/updates-to-progress-tracking-in-14-6-based-on-user-feedback/). + ### Status-based progress reporting Administrators can also switch to [status-based progress reporting mode](../../../system-admin-guide/manage-work-packages/work-package-settings/) for their instance. @@ -109,8 +154,20 @@ OpenProject will automatically show totals for Work, Remaining work and % Comple ![Hierarchy totals for Work, Remaining work and % Complete](hierarchy-totals-days.png) +OpenProject offers two modes for calculating *% Complete* in hierarchy totals: + +- **Weighted by work**: The total % Complete value of a hierarchy is a weighted average tied to Work. For example, a feature with Work set to 50h that is 30% done will influence the total of % Complete of the parent more than a feature with Work set to 5h that is 70% done. + + > [!TIP] + > + > Work packages without *Work* will be ignored. + +- **Simple average**: *Work* is ignored and the *total % Complete* is calculated as a simple average of the *% Complete* values from the work packages in the hierarchy. + > [!NOTE] -> The total % Complete value of a hierarchy is a weighted average tied to Work. For example, a feature with Work set to 50h that is 30% done will influence the total of % Complete of the parent more than a feature with Work set to 5h that is 70% done. +> The administrator of your instance will have selected a mode for the entire instance. If you are an administrator, you can modify this by following our [admin guide on work package settings](../../../system-admin-guide/manage-work-packages/work-package-progress-tracking). + + ### Excluding certain work packages from totals @@ -131,10 +188,12 @@ When switching from Work-based to Status-based mode, the previous value for %&nb - If Work was previously set, it will be retained and Remaining work will be re-calculated based on the other two values - If Work was previously empty, then Work and Remaining work will remain empty + + ## Status- to work-based In Status-based mode, it is possible for work packages to have a % Complete value (defined by the status) without having values for Work or Remaining work. In other words, the Work and Remaining work can be empty. -When switching to Work-based mode, OpenProject will retain the value for % Complete that was set with status. It can then be modified by putting in Work and Remaining work, thereby overwriting the previous value with a new computed value: +When switching to Work-based mode, OpenProject will retain the value for % Complete that was set with status. -![Work estimates and progress pop-over with only the previous % Complete value](progress-popover-percentage-complete-only.png) +Changing progress calculation mode from status-based to work-based will make the *% Complete* field freely editable. If you optionally enter values for *Work* or *Remaining work*, they will also be linked to *% Complete*. Changing *Remaining work* can then update *% Complete*. diff --git a/docs/user-guide/time-and-costs/progress-tracking/openproject_user_guide_percentage_complete_calculation_hint.png b/docs/user-guide/time-and-costs/progress-tracking/openproject_user_guide_percentage_complete_calculation_hint.png new file mode 100644 index 000000000000..e537279c4183 Binary files /dev/null and b/docs/user-guide/time-and-costs/progress-tracking/openproject_user_guide_percentage_complete_calculation_hint.png differ diff --git a/docs/user-guide/time-and-costs/progress-tracking/openproject_user_guide_percentage_complete_manual.png b/docs/user-guide/time-and-costs/progress-tracking/openproject_user_guide_percentage_complete_manual.png new file mode 100644 index 000000000000..9a0504362510 Binary files /dev/null and b/docs/user-guide/time-and-costs/progress-tracking/openproject_user_guide_percentage_complete_manual.png differ