Repository: ansible/ansible
Pull request: Adds documentation about when/why to use roles
##### SUMMARY

Fixes #75508. 

Current more of a starting point for discussion. This PR expands the page about re-use and roles, discussing when to turn a playbook into a role. My basic take is "when it gets complicated enough." I also went back and looked at [role docs from long-ago versions of Ansible](https://docs.ansible.com/ansible/2.3/playbooks_roles.html#roles), when roles were still fairly new. 

##### ISSUE TYPE
- Docs Pull Request

##### COMPONENT NAME
docs.ansible.com
roles

##### ADDITIONAL INFORMATION

N/A


Problem statement:
Docs survey feedback: add tips on when to turn a playbook into a role
### Summary

When is it a good idea to turn a playbook into a role? When should it remain a playbook?

Add some rules of thumb to the role documentation.


### Issue Type

Documentation Report

### Component Name

docs/docsite/rst/user_guide/playbooks_roles.rst

### Ansible Version

```console
$ ansible --version
N/A
```


### Configuration

```console
$ ansible-config dump --only-changed
N/A
```


### OS / Environment

N/A

### Additional Information

None needed.

### Code of Conduct

- [X] I agree to follow the Ansible Code of Conduct

Hints from issue discussion:
Files identified in the description:
* [`docs/docsite/rst/user_guide/playbooks_roles.rst`](https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/user_guide/playbooks_roles.rst)

If these files are incorrect, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/devel/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->

Commit message: adds detail, wordsmithing

Patch to review:
diff --git a/docs/docsite/rst/user_guide/playbooks_reuse.rst b/docs/docsite/rst/user_guide/playbooks_reuse.rst
index a2095ef3643e60..19aea8745ba4c3 100644
--- a/docs/docsite/rst/user_guide/playbooks_reuse.rst
+++ b/docs/docsite/rst/user_guide/playbooks_reuse.rst
@@ -4,7 +4,7 @@
 Re-using Ansible artifacts
 **************************
 
-You can write a simple playbook in one very large file, and most users learn the one-file approach first. However, breaking tasks up into different files is an excellent way to organize complex sets of tasks and reuse them. Smaller, more distributed artifacts let you re-use the same variables, tasks, and plays in multiple playbooks to address different use cases. You can use distributed artifacts across multiple parent playbooks or even multiple times within one playbook. For example, you might want to update your customer database as part of several different playbooks. If you put all the tasks related to updating your database in a tasks file, you can re-use them in many playbooks while only maintaining them in one place.
+You can write a simple playbook in one very large file, and most users learn the one-file approach first. However, breaking the your automation work up into smaller files is an excellent way to organize complex sets of tasks and reuse them. Smaller, more distributed artifacts let you re-use the same variables, tasks, and plays in multiple playbooks to address different use cases. You can use distributed artifacts across multiple parent playbooks or even multiple times within one playbook. For example, you might want to update your customer database as part of several different playbooks. If you put all the tasks related to updating your database in a tasks file or a role, you can re-use them in many playbooks while only maintaining them in one place.
 
 .. contents::
    :local:
@@ -44,6 +44,11 @@ You can select which playbook you want to import at runtime by defining your imp
 
 If you run this playbook with ``ansible-playbook my_playbook -e import_from_extra_var=other_playbook.yml``, Ansible imports both one_playbook.yml and other_playbook.yml.
 
+When to turn a playbook into a role
+===================================
+
+For some use cases, simple playbooks work well. However, starting at a certain level of complexity, roles work better than playbooks. A role lets you store your defaults, handlers, variables, and tasks in separate directories, instead of in a single long document. Roles are easy to share on Ansible Galaxy. For complex use cases, most users find roles easier to read, understand, and maintain than all-in-one playbooks.
+
 Re-using files and roles
 ========================
 


Code review comments:
diff_hunk: @@ -4,7 +4,7 @@
 Re-using Ansible artifacts
 **************************
 
-You can write a simple playbook in one very large file, and most users learn the one-file approach first. However, breaking tasks up into different files is an excellent way to organize complex sets of tasks and reuse them. Smaller, more distributed artifacts let you re-use the same variables, tasks, and plays in multiple playbooks to address different use cases. You can use distributed artifacts across multiple parent playbooks or even multiple times within one playbook. For example, you might want to update your customer database as part of several different playbooks. If you put all the tasks related to updating your database in a tasks file, you can re-use them in many playbooks while only maintaining them in one place.
+You can write a simple playbook in one very large file, and most users learn the one-file approach first. However, breaking the your automation work up into smaller files is an excellent way to organize complex sets of tasks and reuse them. Smaller, more distributed artifacts let you re-use the same variables, tasks, and plays in multiple playbooks to address different use cases. You can use distributed artifacts across multiple parent playbooks or even multiple times within one playbook. For example, you might want to update your customer database as part of several different playbooks. If you put all the tasks related to updating your database in a tasks file or a role, you can re-use them in many playbooks while only maintaining them in one place.
path: docs/docsite/rst/user_guide/playbooks_reuse.rst
text: @user1:
```suggestion
You can write a simple playbook in one very large file, and most users learn the one-file approach first. However, breaking your automation work up into smaller files is an excellent way to organize complex sets of tasks and reuse them. Smaller, more distributed artifacts let you re-use the same variables, tasks, and plays in multiple playbooks to address different use cases. You can use distributed artifacts across multiple parent playbooks or even multiple times within one playbook. For example, you might want to update your customer database as part of several different playbooks. If you put all the tasks related to updating your database in a tasks file or a role, you can re-use them in many playbooks while only maintaining them in one place.
```