We discussed this a bit recently and the DaWGs folks wondered if now was the time we should bite the bullet and move all community guides to their own repository instead of piggy-backing on the Ansible package docs today.
How does this help? - We’d have a new docsite that is unversioned so we’d never have to do backports again! We’d also have the repo in the ansible-community org so the Steering Committee has full rights.
A bigger driver for this is that we know we have to expand our general governance model for the Ansible ecosystem this year. Having a separate docsite for all of this detail might be beneficial.
Of course we could solve the immediate problem by manually editing a list of Steering Committee members in multiple spots to get around our current limitations, but it seems like a good time to consider the future first and how we may want to expand these kinds of guides.
The drawback of moving the guides is they can’t be found on a search on the package docs. We could still leave a ‘community guide’ section with a brief intro and then point to the new docsite to overcome this drawback.
If we decide to move it, the community guide section imo should stay on docs.ansible.com pointing to the new docsite
What to do with the Extending Ansible/Developer guide section? It overlaps with the Contributing to Ansible as it’s a type of broader contribution notion. I think it’s not a part of that section because of historical reasons. It imo should also move if we decide to move the Contributor guides.
So after we move the contributor guides (if agreed), docs.ansible.com will be only about the package usage and Roadmaps, right?
Any ways to avoid broken links? e.g. redirection to corresponding pages in the new location when users use old affected URLs?
@oranod - Normally I’d say yep we can put in redirects for any guides we move. I think this still applies even going from docs.ansible.com to ‘some new site on RTD’, right?
As for the dev guide - Valid point. Some things we’d want to know:
are there currently links/references between what lives in the community guides over to the dev guide (and from dev to community guides). If there are, it would be more painful for readers if they are hopping between two docsites (if we move just the community guides for example). If there are no links (or very very few) - we could go ahead and move just the community stuff to start.
The dev guide is somewhat of a bigger project. We’d need core approval to move it out of their docsite (Ansible Core Documentation — Ansible Core Documentation). And we should really evaluate the whole thing from a contributor perspective to see what still applies (for example, will core EVER accept another module, or should any reference to creating a module in core be removed). Do we need a separate ‘core’ dev guide vs collection dev guide, etc.
I’d also say the developer guide may not be just for contributors. Many ansible users create their own modules etc for local/in-company use that never get ‘contributed’ back to the Ansible ecosystem.
in this case, the community guide should be moved also without all collection dev guides / collection maintainer guides and similar (even doc guides…) as all those things can be also used for developing stuff used internally or to sell it. Surely only Steering Committee and a few other docs can be moved but is it worth to run another docsite to host only a few docs? The issue is that you can use almost all docs there either to contribute or for your personal / business use.
So one of the points was we see this area of Steering Committee docs potentially growing this year as we consider ramping up our overall governance model. But you are correct, it’s only a few pages of docs so to speak that the Steering Committee needs better rights to, and there is another way to do this. So perhaps it is premature to consider a separate docsite for this stuff until we actually need it.
So perhaps it is premature to consider a separate docsite for this stuff until we actually need it.
@samccann probably yes. if there are other bodies other than SC introduced this year, it would make sense to move it out as it’ll probably be broader than or different from the SC responsibility scope (i.e. than the package scope). In that case yes, having all gov docs separately would make more sense.
We’d also have the repo in the ansible-community org so the Steering Committee has full rights.