Removing old/stale scenario guides

@samccann Should I try to fix this, or do you prefer to remove the VMware REST Scenarios completely? Since the link is broken (and probably has been for some time) I tend to remove it. What do you think?

Users will see it in Ansible 9.2.0, and on devel even earlier once community.general 8.2.0 is released (~around the year change).

I mean that from then on they see guides on Community.General — Ansible Documentation resp. Community.General — Ansible Documentation :slight_smile:

Okay so if there’s no objections, I like @mariolenz idea - merge into devel (not split his PR up).

As for vmware rest - given it’s been a busted stub for ages and no one has opened an issue, let’s go ahead and remove it. Thanks!

1 Like

I’m going to follow @mariolenz lead and open issues for the three remaining cloud guides:

  • Open an issue in cloudstack, google, and azure collections to let them know we’ll be removing the guides and consider adding them to their collection
  • Open a PR that removes them.

I would create a PR to do this once ansible/ansible-documentation#965 has been merged.

@samccann I don’t want to put any pressure on you to merge this PR, but I fear I loose track of all the changes if there are too many :face_with_diagonal_mouth:

So let’s merge it as-is (if nobody objects) and then work on the secenario guides that are still left. I would feel much safer with this approach.

Okay I’m putting Remove some scenario guides by mariolenz · Pull Request #965 · ansible/ansible-documentation · GitHub up on the staging site and assuming all looks good, I’ll merge it.

I’ve started with removing the VMware REST Scenario guide but now I think we should remove the Virtualization and Containerization Guides completely.

If I see this right, we’re down to two scenario guides. And @samccann has already opened issues for them:


Yep just need to remove those last two and this beast is done!

Okay, we’ve removed all the stale guides. This is what it looks like now:

So that brings up two options:
1 - we add references to the guides that do exist within collections now, just like the Amazon Web Services Guide looks like in this screencap.
2. We remove it all (the entire COMMON ANSIBLE SCENARIOS)

I’m somewhat leaning toward #2 because we don’t really want to be listing every collection-level guide there when they are included within the collections themselves going forward. But I’m open to being convinced otherwise :slight_smile:

1 Like

I wouldn’t mind having a list here if it’s somehow auto-generated from the collections included in Ansible. But for that:

  1. collections need to be able to mark extra docs as “guides that should be listed here”;
  2. code is needed during the build process (probably in antsibull-docs) that compiles a list of guides and writes it somewhere that can be included/used here.

Also, if we do this, we need to make sure (there’s no automated way to do this) that collections only add one guide for a topic. For example, community.routeros has three guides (Community.Routeros — Ansible Documentation); we don’t simply want to list them all, but there should rather be one top-level guide that links to the other three. (And that doesn’t exist yet.)

I’m not sure whether having such a list of guides justifies that much work (and potential problems, like when the community.routeros maintainer - i.e. me - decides to just mark all three guides as guides to include, and then we end up with a long and confusing list of guides).

1 Like

I tend to remove those scenario guides completely and not add references to the guides that do exist within collections now. They might be hard to keep up to date manually, and I don’t really think it’s worth to automate this.

That is, for devel / next major release documentation. If those guides should also be removed from the current documentation, I probably would add those references there up until then. But that’s not the plan, anyway, or is it?

Sorry late getting back to this. You are correct, there is no plan to change the current documentation. So lets remove that entire COMMON ANSIBLE SCENARIOS section in devel.

1 Like