Move Ansible Community docs into the ansible-community org
gotmax23 opened this issue · 12 comments
Summary
Currently, several community docs such as the Collection Requirements1 and the Ansible Roadmap are stored in the ansible/ansible repository. The SC does not have access to this, and it's difficult for us to keep tabs on changes when they're mixed in with a bunch of ansible-core stuff. Also, it's hard for us to make changes when we need to wait on core review.
I propose moving these docs to a separate repository in the ansible-community org that @ansible-community/steering-committee has access to. I'm not sure whether we can integrate these docs back into the docsite build process or whether we should create a docs.ansible.com subdirectory that houses an independently generated site.
Footnotes
-
This used to be in https://github.com/ansible-collections/overview, but it was moved for some reason. ↩
BTW, some of these docs (like the collection requirements) were only recently moved there (in the last year or so?), they used to be spread out in gh.com/ansible-community/.
backstory on it all - a bunch of community docs were created in a community-doc repo but as I was a party of one, I didn't know how to publish from there so I moved a bunch to ansible/ansible. Now that we have more clever people to ping, we can reconsider where it goes and where it gets published.
One gotcha - there was strong feeling in the past that going to docs.ansible.com/ansible should show all related docs, including community/contributor guides etc. So a person reading how to create playbooks could also notice the community guides and perhaps become a contributor etc.
@oraNod has been thinking deep thoughts around all of this recently as well.
@gotmax23 Hey, I wanted to chime in here. It's great timing. I noticed your comment on Matrix last week that expressed being somewhat weary with those docs residing in ansible/ansible and the overhead that comes with that.
As @samccann mentioned in her comment, I've been looking at this and trying to find a solution that benefits the community. There's several strands here and a lot to unpack but the gist of it is that the community should have a lot more ownership of docs.ansible.com and there is a strong desire to ensure the package docs are a vibrant community project.
I've been kind of quiet about it while working out details and figuring out how to cleanly separate all the strands. It's not just package and core docs. There's also the platform docs on docs.ansible.com. But it seems like things are coming into focus rapidly so I'd like to share a proposal with you and maybe offer it up for consideration within the context of this issue. Please take a look at this doc: https://hackmd.io/Ejh1G6hjSO2DFiJXyUpUsw?both
I am hopeful that we could do a much larger "lift and shift" of community docs out of ansible/ansible. I wonder if it is worth holding on for a bit longer to avoid fragmentation and to preserve SEO integrity on docs.ansible.com. One big move might be preferable to multiple moves.
Thank you and I look forward to hearing your (and everyone's) thoughts.
https://docs.ansible.com/ansible/latest/installation_guide/installation_distros.html is also a candidate for community specific docs
@felixfontein and @gotmax23 Hello. I'd like to bring your attention to this repo: https://github.com/ansible/ansible-docsite
It is a clone of ansible/ansible with content needed to build package docs and core docs. Splitting the docsite into a new repo gives us the flexibility to make adjustments without having core team as the gate. This can be a starting point from which we can iterate a lot faster to get where we want to go with the docs.
I know this might not entirely solve the problem of SC access because it's not under ansible-community but it does position us to make additional changes to address that without much overhead.
That new repo has been configured to use GHA to run the rstcheck and docs-build sanity tests copied in from core. It still depends on ansible/ansible to build the package docs so Matt Clay and nitz added a docs/bin/clone-core.py script that brings in the necessary core bits to support the docs build.
I've tested this with the publishing process for docs.ansible.com (which is done on an internal RH Jenkins instance) and it works just fine. We're planning to update the Jenkins jobs to use the new repo and get a few runs to make sure everything works as expected.
Could you please take a look and see if this raises any issues or concerns for your projects and the community in general?
Thanks and I look forward to discussing this with you both.
PS. The repo name will also change to ansible-documentation but if you've a better idea please say. Cheers.
I'd like to bring your attention to this repo: https://github.com/ansible/ansible-docsite
@oraNod I think the crucial question here is the permissions of the @ansible-community/steering-committee. If the SC does not have access to this, it wouldn't make any difference to us.
@gotmax23 @felixfontein What do you think?
@mariolenz The relocation of docs from the ansible/ansible repo to the ansible/ansible-documentation repo is only the first step. Documentation for various topics (core, community, etc.) are expected to be further split into separate repositories, some of which are likely to end up in the ansible-community org. This first step is simply to decouple the documentation from ansible/ansible so that it can be iterated on more rapidly.
@oraNod I think the crucial question here is the permissions of the @ansible-community/steering-committee. If the SC does not have access to this, it wouldn't make any difference to us.
Right, that was my reason for opening this issue.
Yeah, sorry if I wasn't clear in my earlier response. I recognize that the lift and shift doesn't resolve the access issue but it gives us a lot more flexibility to make additional changes as Matt pointed out.
I really like this (and I fully understand it's a first step, so it will take some more time until all access things are resolved). I guess this also makes it easier to separate the docs build Python requirements from the internal ansible-test dependencies, which is currently making docsite development pretty annoying/hard :)
To give it space for detailed discussion, I moved the lift and shift of /docs from ansible/ansible to ansible/ansible-documentation to #243
This has come up a few times so closing this issue in favor of https://forum.ansible.com/t/should-we-move-the-ansible-documentation-repo-to-ansible-community-org/5224