Merge pull request #9 from sebaherrera07/improve_readme_with_screens_…

…and_uncertainty

Improve README with screens and uncertainty filter

README.md

@@ -15,7 +15,11 @@ We know that it's better to know that we are not going to meet the deadline as e
 So the purpose of this tool is to help you monitor your team's progress and automatically get estimated finish dates, and to make it something quick and easy to use. **You just need to estimate your Jira tickets and the tool will do the rest!**
 
 
-## Considerations
+## :camera: Screens
+To see some of the main screens, please check the [screens](docs/SCREENS.md) page.
+
+
+## :thought_balloon: Considerations
 1. The tool tracks progress and generates estimates for the **Epic**, based on its Issues story points and status (To Do, In Progress, Done, ...).
 
 2. The tool considers all types of Issues (Story, Task, Bug, ...).
@@ -26,18 +30,20 @@ So the purpose of this tool is to help you monitor your team's progress and auto
 
 5. For calculating average velocity and generating estimates is **the unit of time is the week**. This is to avoid having to consider if the team uses sprints, and eventually the sprint length which could be different for each team. Also, estimates in number of weeks should be fine for everyone.
 
-6. By default there are 2 estimations which are calculated based on the average velocity since: (1) the implementation start week; (2) the last 3 weeks. You can also ask for a 3rd estimation based on the average velocity you expect to achieve by passing the `expected_average` parameter to the tool.
+6. By default there are 2 estimations which are calculated based on the average velocity since: (1) the implementation start week; (2) the last 3 weeks. You can also ask for a 3rd estimation based on the average velocity you expect to achieve by using the `Expected average` filter.
+
+7. The tool considers that weeks start on Monday and end on Sunday. Why do I mention this? Because if you started the implementation of a project on a Friday, the tool will consider that the implementation started on the previous Monday, and therefore your average velocity will be lower than expected. In this case you can either live with this difference, or use the `Implementation start date` filter and say implementation started the following Monday.
 
-7. The tool considers that weeks start on Monday and end on Sunday. Why do I mention this? Because if you started the implementation of a project on a Friday, the tool will consider that the implementation started on the previous Monday, and therefore your average velocity will be lower than expected. In this case you can either live with this difference, or pass the `implementation_start_date` parameter to the tool and say implementation started the following Monday.
+8. If you want to estimate just a subset of an Epic, you can make use of Jira labels to filter the Issues you want to consider. First label your Issues in Jira, and then use the `Label` filter.
 
-8. If you want to estimate just a subset of an Epic, you can make use of Jira labels to filter the Issues you want to consider. First label your Issues in Jira, and then pass the `labels` parameter to the tool.
+9. The tool allows you to consider a level of uncertainty when calculating an estimation, with 5 possible values: Empty, Low, Medium, High, Very High. For each value you can set a percentage associated to it, by setting the `LOW_UNCERTAINTY_PERCENTAGE, MEDIUM_UNCERTAINTY_PERCENTAGE, HIGH_UNCERTAINTY_PERCENTAGE, VERY_HIGH_UNCERTAINTY_PERCENTAGE` environment variables. What this will do is, for example, if right now you have 20 story points remaining, and you set the `MEDIUM_UNCERTAINTY_PERCENTAGE` to 20% and select `Uncertainty level` filter to Medium, the tool will consider that you have 24 story points remaining and calculate the number of weeks remaining based on that.
 
-9. The calculations are more accurate when you estimate **ALL** the Issues and after multiple weeks of work (the first few weeks is expected to see unaccurate estimates).
+10. The calculations are more accurate when you estimate **ALL** the Issues and after multiple weeks of work (the first few weeks is expected to see unaccurate estimates).
 
-10. The tool works for Scrum, Kanban, or any other Jira board type. By default it might just work with Scrum boards by using the existing story points field, and if you need to use another custom field, you should set the `JIRA_STORY_POINTS_FIELD_CODES` environment variable, which allows comma separated values (e.g. `customfield_10016,customfield_10034`)
+11. The tool works for Scrum, Kanban, or any other Jira board type. By default it might just work with Scrum boards by using the existing story points field, and if you need to use another custom field, you should set the `JIRA_STORY_POINTS_FIELD_CODES` environment variable, which allows comma separated values (e.g. `customfield_10016,customfield_10034`)
 
 
-## Connecting to your JIRA instance
+## :electric_plug: Connecting to your Jira instance
 
 ### Create an API token
 Extracted from: [Manage API tokens for your Atlassian account](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)
@@ -62,7 +68,7 @@ JIRA_USERNAME=user_email@example.com
 ```
 
 
-## Managing users
+## :busts_in_silhouette: Managing users
 There are no web pages for creating or deleting users.
 
 You can create users with the following command in the `rails console`:
@@ -78,7 +84,7 @@ User.find_by(email: 'admin@example.com').destroy!
 ```
 
 
-## Development
+## :computer: Development
 ### Ruby version
 ```
 3.1.2
@@ -107,9 +113,9 @@ bundle exec bundler-audit
 ```
 
 
-## Contributing
+## :raising_hand: Contributing
 Bug reports and pull requests are welcome on GitHub at https://github.com/sebaherrera07/jira-project-estimator.
 
 
-## License
+## :ledger: License
 This software is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

app/views/about/index.html.erb

@@ -5,22 +5,34 @@
   <ol>
     <li>The tool tracks progress and generates estimates for the <strong>Epic</strong>, based on its Issues story points and status (To Do, In Progress, Done, ...).</li>
     <br/>
+
     <li>The tool considers all types of Issues (Story, Task, Bug, ...).</li>
     <br/>
+
     <li>The tool does not track progress or generate estimates for Issues without Epic.</li>
     <br/>
+
     <li>The tool does not consider Sub-Tasks.</li>
     <br/>
+
     <li>For calculating average velocity and generating estimates is <strong>the unit of time is the week</strong>. This is to avoid having to consider if the team uses sprints, and eventually the sprint length which could be different for each team. Also, estimates in number of weeks should be fine for everyone.</li>
     <br/>
-    <li>By default there are 2 estimations which are calculated based on the average velocity since: (1) the implementation start week; (2) the last 3 weeks. You can also ask for a 3rd estimation based on the average velocity you expect to achieve by passing the <strong><i>expected_average</i></strong> parameter to the tool.</li>
+
+    <li>By default there are 2 estimations which are calculated based on the average velocity since: (1) the implementation start week; (2) the last 3 weeks. You can also ask for a 3rd estimation based on the average velocity you expect to achieve by using the <strong><i>Expected average</i></strong> filter.</li>
     <br/>
-    <li>The tool considers that weeks start on Monday and end on Sunday. Why do I mention this? Because if you started the implementation of a project on a Friday, the tool will consider that the implementation started on the previous Monday, and therefore your average velocity will be lower than expected. In this case you can either live with this difference, or pass the <strong><i>implementation_start_date</i></strong> parameter to the tool and say implementation started the following Monday.</li>
+
+    <li>The tool considers that weeks start on Monday and end on Sunday. Why do I mention this? Because if you started the implementation of a project on a Friday, the tool will consider that the implementation started on the previous Monday, and therefore your average velocity will be lower than expected. In this case you can either live with this difference, or use the <strong><i>Implementation start date</i></strong> filter and say implementation started the following Monday.</li>
     <br/>
-    <li>If you want to estimate just a subset of an Epic, you can make use of Jira labels to filter the Issues you want to consider. First label your Issues in Jira, and then pass the <strong><i>labels</i></strong> parameter to the tool.</li>
+
+    <li>If you want to estimate just a subset of an Epic, you can make use of Jira labels to filter the Issues you want to consider. First label your Issues in Jira, and then use the <strong><i>Label</i></strong> filter.</li>
+    <br/>
+
+    <li>The tool allows you to consider a level of uncertainty when calculating an estimation, with 5 possible values: Empty, Low, Medium, High, Very High. For each value you can set a percentage associated to it, by setting the <strong><i>LOW_UNCERTAINTY_PERCENTAGE, MEDIUM_UNCERTAINTY_PERCENTAGE, HIGH_UNCERTAINTY_PERCENTAGE, VERY_HIGH_UNCERTAINTY_PERCENTAGE</i></strong> environment variables. What this will do is, for example, if right now you have 20 story points remaining, and you set the <strong><i>MEDIUM_UNCERTAINTY_PERCENTAGE</i></strong> to 20% and select <strong><i>Uncertainty level</i></strong> filter to Medium, the tool will consider that you have 24 story points remaining and calculate the number of weeks remaining based on that.</li>
     <br/>
+
     <li>The calculations are more accurate when you estimate <strong>ALL</strong> the Issues and after multiple weeks of work (the first few weeks is expected to see unaccurate estimates).</li>
     <br/>
+
     <li>The tool works for Scrum, Kanban, or any other Jira board type. By default it might just work with Scrum boards by using the existing story points field, and if you need to use another custom field, you should set the <strong><i>JIRA_STORY_POINTS_FIELD_CODES</i></strong> environment variable, which allows comma separated values (e.g. <i>customfield_10016,customfield_10034</i>)</li>
   </ol>
 </div>

docs/SCREENS.md

@@ -0,0 +1,10 @@
+# :camera: Screens
+
+### :book: Epic details
+![Epic details](images/1_epic_details.png)
+
+### :chart_with_upwards_trend: Epic progress
+![Epic progress](images/2_epic_progress.png)
+
+### :bookmark: Epic issues
+![Epic issues](images/3_epic_issues.png)