Can we group all ecosystem project docs under the docs.ansible.com domain?

Project Discussions
, ,
1

This is just to kickstart the discussion. Today, we have the following docsites:

Ideally, we’d want something like:

docs.ansible.com/ansible
docs.ansible.com/ansible-core
docs.ansible.com/ecosystem
docs.ansible.com/molecule
…

etc etc.

There are SEO implications to all of this, that @oranod is likely better able to summarize, though you can read a bit on it from this post in a related topic.

1 Like
2

Thanks for kickstarting the topic @samccann

The direct answer to your question is yes. Putting the package docs and ecosystem project docs under the same docs.ansible.com subdomain is a good outcome because it keeps all the content together. Users have one stop for Ansible community docs. Besides the Ansible package is a project in the ecosystem, not a separate thing.

How can we get there?

One option could be using a reverse proxy. We’ve talked about this one in the DAWGs meetings and elsewhere as part of the effort to host ansible-core content on Read The Docs. I’ve also invested some time exploring the option and trying to set up a small demo. At the end of the day, the proxy server just doesn’t seem like the right solution.

A proxy server means more reliance on RH infrastructure. It’s always great that RH can provide infra to support the community but it creates a barrier to access for community ownership / maintenance, which is going in the opposite direction of opening up tooling and infra to community members. Tied with this is the fact that we’d need to update the proxy server config periodically, not to mention big potential headaches for the Read The Docs support team. A proxy server doesn’t seem like a great long-term option in terms of maintenance and risks putting us in the place where it becomes even harder to migrate the package docs safely away from the web server it currently runs on (also on RH infra).

What does that leave us with? Well, a seemingly obvious move for the package docs (everything under docs.ansible.com/ansible) is to Read The Docs. A challenge the ever-present reality that it requires a lot of resources to build the package docs. We need a pretty chonky host. There’s ongoing work in that area but, taking it back to just where we host the docs, is Read The Docs acceptable to the community? I feel like we never got a definitive answer on that.

Should we host the package docs somewhere other than Read The Docs? Should we just leave them on the current web server but continue to make it so community can trigger builds and handle the full release cycle?

Should we just accept the fact that “docs.ansible.com” and content on Read The Docs will be on different domains? The plan is still for the community to take control of “ansible.com” so we can create a new ecosystem docs subdomain.

As we go into 2024 I’d just like to reboot this conversation. It did get kicked around, we made some progress, went down some ratholes. I think a lot of this also got buried in HackMD documents before we launched the forum.

This year I’m really optimistic that we’ll tackle the issue with the build side of things. That’s what started all of this, opening up access for build and deploy jobs to community. I guess the question is pretty simple, if we can get tame the build then where is the best place to deploy?

3 Likes
3

I don’t personally know what is available beyond ReadTheDocs, but they do have some comparison pages that are interesting to compare features with.

So I agree all the ecosystem projects are well-suited to ReadtheDocs - it’s feature rich, extremely simple to use, and open to adding community members to support docs builds.

But is it the right place for our ‘flagship’ so to speak? Ansible package docs got 34M hits last year. Now with the caveat that it’s dated, RTD blog states they had 700M hits back in 2021, including a major site for the government of Brazil. That does give me the warm fuzzy that the site can handle the traffic from Ansible package docs, if we try to host them there.

So, if we could get over the technical hurdles, we get a stable system where people are actively working on improvements and open source. Today, if there’s a problem with the build and in the internal-to-redhat Jenkins jobs, we can’t get the community to review/improve/troubleshoot problems. Just looking at the amount of innovation that’s happened in the ansible/ansible-documentation repo since it was lifted and shifted out of ansible/ansible - I’ll say great things happen when we enable the community to drive change.

But it goes back to - what does the community want and need? @felixfontein @gotmax23 -as two people heavily involved in the package docs build, what are your views here?