Hi all,
As part of the continuing work on Ansible ecosystem documentation we’re planning to redirect the ecosystem page from “docs.ansible.com” to “ansible.readthedocs.io”. This redirect will remove the duplicate listing of ecosystem projects and create a single place for all ecosystem content.
Before we add the redirect we’d like to get your feedback. Please reply to this topic, leave a comment on the pull request , or head over to the docs channel on Matrix and let us know your thoughts.
There’s two things I find confusing:
1 - the ecosystem documentation now includes a page that shows all the projects (same content as the old page but different UI) as well as what we hope will be a growing set of cross-project guides (like the EE getting started). I find that experience a bit jarring, but as I mentioned in matrix, it could just be that I’m used to the ‘old’ way so to speak. So wanted to see if others see an issue in that regard or not.
Thanks for the feedback @samccann
For 1, it’s a little hard to work with that if I’m being honest. How do you mean the experience is jarring? Is it because the ecosystem page is in the left hand navigation?
Do bear in mind that specific pointers to the ecosystem will go directly to this page, such as the link on “docs.ansible.com” as well as the community website.
For 2, if we made that the homepage then we wouldn’t have ecosystem.html in the url. Although maybe it’s not really important. Also it seems necessary to give a bit of context as to what that docsite is all about, which is covered in index.html. There’s also a direct link to the ecosystem page at the top.
Thanks again for the comments! I hope we hear some more from folks in the community about this and can make it better.
Thanks. I think the ‘jarring’ bit might just be me. If no one else mentions this, I think we can assume I’m just a curmudgeon and used to the old page 
As for #2 - this url on its own seems misleading - Ansible ecosystem documentation
As in it’s just the ecosystem docsite, not all ansible docs. Is there a way to get ecosystem into the url at that level? I think there’s a hi-level plan that I’m probably forgetting here, but what I see now:
Ansible ecosystem documentation == ecosystem docsite
Ansible Molecule - one of the projects in the ecosystem
But no indication that this site does not have the full docs for the package. Will that be fixed by DNS magic at some point so it becomes for example, docs.ansible.com/ecosystem/en/latest?
I left the suggestion somewhere else, but seeing we have a discussion going here, I might as well add to it:
For the redirects, we probably want to use temporary ones, to avoid overwriting search engine indexes and the like with the readthedocs domain.
Hey @samccann, you mean the experience of mixing the “ecosystem” with the “getting started guides” in the same landing?
If that’s the meaning, then I think I agree.
I wouldn’t expect to find the getting started guides there next to the Ecosystem page. I’m trying to think where would I look for getting started guides, even if they were cross-project, I would expect each project linking to their respective guides (and if it involves more projects than one, then the same guide appearing in all of them).
Thinking on this and considering the conversations we were having around the domain and the redirect, I was thinking how the Custom domains — Read the Docs user documentation and Subprojects: host multiple projects on a single domain — Read the Docs user documentation options could work for this.
Unless we are using the parent docs.ansible.com as @samccann mentions in the future for all things, including ecosystem, wouldn’t an ecosystem.ansible.com custom subdomain work here for ex. instead of the ansible.readthedocs.io domain?
I
@samccann Maybe an entry for the package docs on the left nav would be useful? For sure we want to avoid fragmentation with the package docs or confusion and what I feel like you’re saying - at least in part - is that it isn’t clear enough how this page relates back to the Ansible package docs?
To recap a bit, the ideal outcome is to end up with:
docs.ansible.com/ansibledocs.ansible.com/ansible-coredocs.ansible.com/ecosystemdocs.ansible.com/moleculeThe end goal is to have all project documentation available under the docs.ansible.com subdomain.
We could host everything on readthedocs and add the CNAME to the “ansible” namespace. There has been some reluctance from the community to go this route with the package docs so it would need to go to a vote. Before we can even do that we need to tackle the build and tame down the resource consumption. The full sphinx build for “webdocs” needs a chonky host. As it stands now the build puts us in the range of the RTD enterprise plan, which is quite costly (note that the Ansible community at Red Hat supports RTD with a gold membership).
Anyway switching to RTD could banjax SEO for the package docs. That belongs to the community and is very valuable. Right now there is some work going on to examine a proxy configuration on the http server so that docs.ansible.com/ansible-core → readthedocs.io/projects/ansible-core. If this experiment is successful then we can safely move the core docs to RTD hosting. That content joins the rest of the ecosystem. We’d also have a way forward with the package docs pending all the work to break that build down, which we’ll figure out. Porting the makefile over to nox is likely to be a good way forward here and will allow us to do things in stages.
We’ve also looked at ecosystem.ansible.com. There’s a hackmd or gh issue around here some place with the details. IIRC the TL;DR is that’s a reasonable backup move but not the ideal outcome because it leaves the Ansible documentation split. The package is part of the ecosystem too. And once that subdomain gets created…
@Leo I get what you mean with the same guide appearing in each project but that raises maintenance issues and the need to single-source. That also results in multiple entry points for users which makes it more difficult to provide guided signposts through content.
For me it wasn’t at first sight. I could use some extra recap on the plan there around ansible.readthedocs.io and docs.ansible.com relation.
Maybe I’m getting something wrong and I need the recap mentioned above, but wouldn’t ansible.readthedocs.io be as fragmenting as ecosystem.ansible.com? I’m only suggesting that one if we are supposed to have both (as in docs & ecosystem) to avoid a third party domain.
Unless we are moving everything under docs.ansible.com and to RTD (and that subdomain as the custom one in RTD), then it looks like we are splitting.
Ok, I see your point. I was thinking on the link only within each subproject, which shouldn’t require much maintenance, but I still didn’t like it either.
Maybe we can “separate” the ecosystem lading with a couple of categories:
So they don’t get mixed?
I hope we can keep everything in the docs.ansible.com domain, no matter whether the pages are hosted on readthedocs or the web server.
The point ansible.readthedocs.io that is as fragmented as ecosystem.ansible.com is true but we’re still pulling things together. Earlier in the year we had multiple x.readthedocs.io domains but now we’ve converged a bunch of projects under the ansible namespace. Next step is to join things up with the package docs. If we still want to do that and have a single subdomain then I don’t see the need for ecosystem.ansible.com.
ansible.readthedocs.io → docs.ansible.com 
ansible.readthedocs.io → ecosystem.ansible.com → docs.ansible.com 
We could certainly create a PR to separate the ecosystem landing with two categories but I think that maybe divides things in a way that might not be clear for users? I can see what you mean but when I try and visualize that docsite navigation in my mind it seems like it results in unnecessary nesting. Also maybe it would be a lot harder for users to know where to look.
Perhaps it would make sense to keep the ecosytem page on docs.ansible.com as is with the list of projects and then highlight the ecosystem docsite as a link on that page. I think the redirect would be a bit jarring, and I don’t think the list of ecosystem-wide projects and the general ecosystem guides/docs need to be part of the same mkdocs site.
yes i think this was the point I was trying to make. We are using ‘ecosystem’ for two different things:
1 - the page that lists all the projects we have (ansible lint, molecule, etc etc) and will one day include ansible-core
2 - a documentation SET that includes cross-project guides like the current EE getting started guide.
So I’d be in favor of leaving the ecosystem page on docs.ansible.com as well. And keeping this new site as just for the cross-project how-to guides.
maybe we can put it to a vote? I’m not trying to force this and welcome the opportunity to be shown the redirect isn’t the right approach.
for a bit more detail on why I’m leaning towards the redirect, when I created the ecosystem page on “docs.ansible.com” it didn’t really have anywhere else to go and all the projects were scattered across various readthedocs.io namespaces. at that time the more user-journey centric structure to the “docs.ansible.com” landing pages didn’t exist either. and it was kind of a case of “let’s put the ecosystem page here because we don’t have anywhere else for it to go”.
so, like we’ve seen with the package docs, the ecosystem page was more or less shoved in because a rightful home didn’t exist elsewhere. for me it makes a lot of sense as the top-level on the ansible namespace in readthedocs. and it is true that projects in the ecosystem don’t necessarily need to have their docs in the ansible namespace (or even hosted on RTD).
it seems to me that if we’re going to have a docsite for the ecosystem then it makes sense to put the page that lists all the projects in the ecosystem within the docsite.
also I still don’t get how the redirect would be “jarring”. it’s mainly for anyone who has “Ansible Documentation” bookmarked. the ecosystem links on the docsite and website will point directly to Ansible ecosystem - Ansible ecosystem documentation
@maxamillion I don’t want to put you on the spot about it but noticed you approved the PR that redirects the ecosystem page from \docs.ansible.com to \ansible.readthedocs.io. We’ve been debating it a little and your point of view would be beneficial to the discussion here. Cheers.
I’ve lost track of the overall strategy for the various docs changes, including this one. I would find it much easier to discuss and evaluate individual questions like this one if I understood the context, the larger strategy. What are the overall goals of these changes? How does this particular change fit into those goals? What do we want the documentation to look like in a year, and why?
What would happen to the Ansible ecosystem nav entry on docs.ansible.com? Would that link to https://ansible.readthedocs.org?
@acozine Hi, thanks for chiming in. It’s always good to get your point of view on these things. I’ve mentioned the overall strategy a bit in my earlier reply but the urls automatically expanded to show the title instead of the actual url so it probably wasn’t clear. Hopefully that helps with your question about the overall goal, which is basically to have all project docs under docs.ansible.com even if they are hosted on RTD.
Another goal is to continue moving towards that user journey-based approach with the docs landing pages. As I mentioned elsewhere the ecosystem page isn’t really a journey, it’s a list of projects and doc links. We put the ecosystem page on docs.ansible.com a year ago kind of because it didn’t have anywhere else to go. Now that we have the ecosystem docsite (GitHub - ansible/ecosystem-documentation: Task-oriented, cross-project documentation for the Ansible ecosystem) it seems like that is the logical home for the ecosystem page.
It might also be worth noting that this redirect is something that the community team at Red Hat captured as a task in this epic: [epic] Create Common community documentation site · Issue #237 · ansible-community/community-team · GitHub Just wanted to point that out. It’s totally fine that folks question the redirect and - like I’ve said - I really appreciate everyone taking the time to give their thoughts to make sure we arrive at the best outcome here. But it is something we’ve discussed and had in plan, not just me sending a random PR. I know there’s a lot flying around and it’s easy for little details to fall through cracks.
Perhaps a TL;DR for this redirect is that it is a continuation of the work to organize project docs in a logical way so that things reside in places where users would expect them to be and not “shoved” in because there’s not a better alternative. Over the past year the community team has focused on improving and building a better web presence and this is a small part of that effort.
Looking at the end goal of achieving docs.ansible.com/ecosystem - it would likely be preferable for that url to point to the ecosystem docsite than a single page with a bunch of links.
Even if it turns out that we create a new subdomain, ecosystem.ansible.com, then it seems superfluous to have that in addition to docs.ansible.com/ecosystem. We should be sending users to less places to find content.
@gotmax23 Yes, I was thinking specifically Ansible ecosystem - Ansible ecosystem documentation instead of the home page though.
It would be the same for the new website: update ecosystem url by oraNod · Pull Request #317 · ansible-community/community-website · GitHub
What if we move the ecosystem to ansible.com/ecosystem instead of read the docs?
I’m migrating pages to the new community site, among which are ansible.com/awx and ansible.com/galaxy. Apparently those two pages get high amounts of traffic so we need to keep them. It seems like a good idea to elevate the ecosystem page to the top-level domain in the new year. Anyone else think so? @samccann ?
I quite like having it on the website. Makes sense there to me. Should there be links to both docs and the github repos for each?