# Community/contributor documentation

We have docs in three places today for contributors:
* ansible/ansible in the [community folder](https://github.com/ansible/ansible/tree/devel/docs/docsite/rst/community)
* [ansible/community-docs](https://github.com/ansible/community-docs) - more collection focused
* [ansible-collections/overview](https://github.com/ansible-collections/overview) - has deeper collection contribution details

This document lists out some options we have and the pros/cons of each.

**NOTE:** In a prior discussion, the docs community felt strongly that keeping the docs visible in one place means a better user experience, helps folks interested in Ansible learn about community engagement (in other words, someone coming to the docsite for user help can see community topics as well as user topics), could offer consolidated search, and generally integrates the contributor community with the user community. This was also the driving reason behind including collections on docs.ansible.com/ansible after the collection split - so we had one place that included everything

## Actions

1. Define options - This document
2. Mock screenshots and example URL for each proposal
3. See how other projects have solved this
1. Which projects - Maybe look at Sandra/acozine's gDoc on comparison of landing pages
2. Detail how they have achived this
5. Web analytics
1. How do people end up in the Community guide (from other parts of ansible docs, or external)
2. How many visitors do we have to (userguides; community; dev_guide)
6. Share and get feedback
3. community-topics
4. Docs Meeting
5. Community Meeting
6. r/ansible
7. Do we have email addresses from those that completed doc survey?

## What might the requirements be in a few years?

1. Clearer separation between upstream (community) and downstream (product) documentation
2. Docs for more/other projects
3. Does ansible-core become a smaller part of Ansible docs over all?
4. Might we completly redo site search?
5. Collection docs might be in GalaxyNG
6. `ansible-test` might be out of ansible-core into it's own released package.
7. If we have a "Content Creator" personal, should lint/molecule/vscode be included in there.

## Supporting Analytics

For the first 10 days of December, we have the following hits on different docs:
* User guides- 333K ( including installation and porting guides)
* contributors 106k (85.6K for community, 19.7k for dev guide)
* collections - 394K (197K ansible.builtin only)

## Options

1. Merge ansible/community-docs into ansible/ansible community guide.
2. Create a generic 'community' guide that works across all projects, then have separate repos for each specific project but also a tool like `antsibull-docs` that will pull all those rst files into the ansible/ansible docs build and docsite so we keep one docsite for all.

Either approach could result in something like the following:

The major differences between the two options is that in option 1, all RST files live in ansible/ansible. In option 2, we move collection-based files out to a separate repo, since they don't apply to ansible/ansible and its specific branches, and we then update `antsibull` to pull in the rst files from this other repo during build time. From the end user perspective, both options display the same on docs.ansible.com

## Pros and Cons

This section lists the good, the bad, and the ugly for each of these options.

### 1. Merging all into ansible/ansible

| Pros | Cons |
|- | - |
| Keeps all docs in one repo | Core team prefers docs move out of repo. Collection contributore docs have nothing to do with core and this category of docs will only grow over time (devTools etc). |
| Fasted to implement and move on to other priority items | Collection based docs don't 'version' the same as ansible-core so don't match the core branch strategy|

## 2. Separate repos, one docsite

We could create a tool like `antsibull-docs` that pulls all the appropriate rst files from these various repos into a set of contributor guides on docs.ansible.com/ansible. From the end user perspective, it is all still one searchable docsite, but under the covers, we would have a 'community getting started' that is common to all projects, and then individual contributor guides for core, collections, and possibly devtools in the future.

| Pros | Cons |
| - | - |
| Allows individual projects to control their own contributor guides in their own repos, but brings them all into the one docsite users are reading today (docs.ansible.com/ansible). | Someone has to code and maintain a new tool. |
| Search can find all guides in one place | May be confusing Ansible docs reader to find the contributor guide for molecule/lint in the search results for example |
| Moves some files out of ansible/ansible and thus not tied to its branching scheme etc | Still adds more complexity to the ansible/ansible docs build when that team really wants most if not all docs and docs processes out of that repo |

**Note**: This option would also require two 'buttons' on each HTML page - one to open an issue in the correct repo, the other to Edit on GitHub - again in the correct repo.

# Old, eliminated options
Saving for posterity but these two options are considered undesirable and no longer under consideration

## 3. Move all non ansible-core contributor details to separate repo
(note: these pros/cons assume we cannot pull individual files from another repo into the docs published from ansible/ansible - aka assumes a separate docsite for community contributions. )

| Pros | Cons |
| - | - |
| Clear separation of collection contributors from core contributors | Will still require many links back to core docs and thus cause users to 'hop' between docsites |
| Allows `Edit on Github` to work | Search on main docs will no longer find this detail.|
| | Creates a new docsite that the 'docs team of one' will need to maintain |

**NOTE:** impact on google search results TBD - some feel it may make things less findable

This will also require redirects so users find the new home for this content.

## 4. Generic contributor guide with specifics in other repos

This approach could work either way:
* Generic contributor guide in ansible/ansible, with a separate core-specific guide. specific contributor guides for collections, awx, ansible-lint, etc exist in their repos and published 'somewhere'.
or
* Generic contributor guide in some other repo, and then each individual project repo includes only their specific details

| Pros | Cons |
| - | - |
| Covers the generic material common to all projects in one place (getting involved in Ansible, irc/matrix, meetups,etc) | Will still require many links between docsites unless we duplicate the information in both places. |
| Allows each project to control their own unique requirements and not burden ansible/ansible with it all. | Search on any one docsite will no longer find all details needed to contribute to an ansible project. |
| Allows the `Edit on Github` button to work | |

###### tags: `todo`