Making community docs a separate project to ansible/ansible

[samccann]

Summary

This issue proposes to separate the source content for Ansible community documentation published at docs.ansible.com/ansible and docs.ansible.com/ansible-core from the ansible/ansible repository.

This proposal is intended to benefit the Ansible community by decoupling community doc initiatives from core release cycles. Additionally this proposal removes the Ansible Core team as the gate for other changes that will meet community needs, such as putting source content for docs.ansible.com under the direct control of the Steering Committee.

It is a first step towards providing greater access and ownership of docs.ansible.com to the Ansible community.

Summarized details

The Ansible core team is facilitating a lift and shift of docs/docsite from ansible/ansible to ansible/ansible-documentation. This is an interim step toward full community/Steering committee control of Ansible package documentation.

Testing and feedback timeframe

To ensure community members have time to evaluate and ‘test drive’ this proposed solution, we have the ansible/ansible-documentation repository up and running with a jenkins job. We will use this repo starting on Thursday, June 15th, for a two week period - ending June 29th, 2023.

All docs PRs will happen in the new repository during this test period and be published regularly to devel docs to see if we come across any technical glitches.

Full details

See #240 for discussion on some of the drivers for this change as well as https://hackmd.io/@ansible-community/rkzSKCEvh for the nitty gritty details.

Additional Information

No response

[samccann]

If you are trying the docs build locally on this new repo, you need one more step:
python3 docs/bin/clone-core.py

We'll find an appropriate place to document that but just fyi.

[gotmax23]

Thanks for typing up this proposal. I have one question. The proposal says:

this proposal removes the Ansible Core team as the gate for other changes that will meet community needs, such as putting source content for docs.ansible.com under the direct control of the Steering Committee.

but the rest of it only talks about the ansible/ansible-documentation repository which is not under the control of the SC.

[oraNod]

@gotmax23 This proposal is intended to offer a first step towards the SC gaining full control of source files to resolve #240

There are quite a few strands in here - e.g. the new repo includes a fully functional copy of the hacking folder - and taking an incremental approach safeguards docs.ansible. Ultimately the lift and shift will give a lot more flexibility and autonomy for the Ansible community.

I'll update that hackMD. Cheers.

[sakeleo213]

Thank You for typing This Proposal.
GTA 5 Android Apk OBB

[acozine]

There are advantages to having community ownership of community documentation.

However, there are serious disadvantages to having the documentation in a separate repo from the code. A separate docs repo makes it harder to require documentation for every new feature, and easier to forget to update the documentation in general.

We've discussed this in the DaWGs meeting, but I wanted this ticket to reflect the conversation as well.

[samccann]

Something else that came up - today, the core team keeps an eye on all issues and fixes many docs issues since they show up in the core triage/backlog etc. We'd want to ensure that level of stewardship continues in the new docs repo.

[oraNod]

@gotmax23 We've been looking into settings with the new repo. It does look like we have the ability to add Steering Committee members more access to ansible/ansible-documentation:

Does this look like it would address the issue around access to docs? Or do you think it would be preferable to move a subset of content into the ansible-community org? Thanks.

[gotmax23]

I think giving at least some SC members commit on ansible/ansible-documentation is a good start. We can look into moving specific things out later.

[oraNod]

@gotmax23 What do you think about creating a "steering committee" team here? https://github.com/orgs/ansible/teams

That way we can grant access to the team and add/remove folks from the team. Preferably someone in the SC could create and populate the team.

[gotmax23]

That sounds good to me. I'm not sure whether I have sufficient privs, but let me know how I can help.

[oraNod]

@gotmax23 and @felixfontein To start I've added you both as maintainers to a new team: https://github.com/orgs/ansible/teams/steering-committee

I've also added this team with maintainer access to the https://github.com/ansible/ansible-documentation repository.

Please let me know if that works OK or if you have any other thoughts to improve. I can add more folks to the team as well, if you think we should go ahead. Cheers.

[felixfontein]

I tried to add all @ansible-community/steering-committee members to @ansible/steering-committee, but I couldn't add Alexei, Brian, Mario, Markus, and James as they aren't members of the @ansible organization. I don't know who can change this...

[gotmax23]

I don't know who can change this...

@gundalow or anyone else in https://github.com/orgs/ansible/people?query=role%3Aowner.

[oraNod]

@samccann Think we're good to close this one?

[samccann]

Did the people with missing rights from #243 (comment) get added?

[oraNod]

Hmm. No, I think we need to wait on @gundalow for that (still on PTO for another while). What if we break that into a separate topic because it's kind of tangential to this one? That might also provide an opportunity to revisit the steering committee membership.

[samccann]

@gundalow assigned this issue to himself so if you do create another issue (maybe on the community-team repo as it doesn't need discussion) to update the membership, then assign it to him pls so it shows up on his radar.