Should we move community guides to their own docsite and repo?

Project Discussions
,
1

We’ve had a problem in the documentation repo where we cannot easily add all the current steering committee members to the repository as maintainers. There are some forum discussions here depending on this access so that Steering Committee members can approve any changes to their documentation.

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.

  • Which guides - Everything under ‘Contributing to Ansible’.
  • How does this help? - We’d have a new docsite that is unversioned so we’d never have to do backports again! :slight_smile: 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.

What do folks think?

1 Like
2

@samccann

  • 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?
3

@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.

4

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.

5

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.

1 Like
6

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.

7

Based on Should we move the ansible-documentation repo to ansible-community org? - #10 by sivel, we are reviving this discussion on splitting the docs repos. We’ll use Return span of control of core docs back to core team · Issue #1538 · ansible/ansible-documentation · GitHub to track this in github.

Meanwhile, I’ll add a post here with the current list of files excluded from the core docs as a starting point, but there are a number of valid comments earlier in this topic that we need to consider as well.

8

This is a wiki post of files we will consider moving to a repo outside of the Ansible org. This is a work in progress and reflects files and directories in the current ansible/ansible-documentation repo.

 'network' (network user and developer guides)
    'scenario_guides', (these are all stub pages now)

The following are for contributing to collections. Some apply for any collection, and some are specific to collections within the package:
    'community/collection_contributors/test_index.rst',
    'community/collection_contributors/collection_integration_about.rst',
    'community/collection_contributors/collection_integration_updating.rst',
    'community/collection_contributors/collection_integration_add.rst',
    'community/collection_contributors/collection_test_pr_locally.rst',
    'community/collection_contributors/collection_integration_tests.rst',
    'community/collection_contributors/collection_integration_running.rst',
    'community/collection_contributors/collection_package_removal.rst',
    'community/collection_contributors/collection_reviewing.rst',
    'community/collection_contributors/collection_requirements.rst',
    'community/collection_contributors/collection_unit_tests.rst',
    'community/maintainers.rst',
    'community/contributions_collections.rst',
    'community/create_pr_quick_start.rst',
    'community/reporting_collections.rst',
    'community/contributing_maintained_collections.rst',
    'community/collection_development_process.rst',
    'community/collection_contributors/collection_release_without_branches.rst',
    'community/collection_contributors/collection_release_with_branches.rst',
    'community/collection_contributors/collection_releasing.rst',
    'community/maintainers_guidelines.rst',
    'community/maintainers_workflow.rst',

Definitely controlled by Steering committee and requires approval for any changes:
    'community/steering/community_steering_committee.rst',
    'community/steering/community_topics_workflow.rst',
    'community/steering/steering_committee_membership.rst',
    'community/steering/steering_committee_past_members.rst',
    'community/steering/steering_index.rst',

General artifacts from pulling multiple docsites out of the same source:
    'dev_guide/ansible_index.rst',
    'dev_guide/core_index.rst',

The following have been removed already (and should be removed from conf.py exclusions :-): 
    'dev_guide/platforms/aws_guidelines.rst',
    'dev_guide/platforms/openstack_guidelines.rst',
    'dev_guide/platforms/ovirt_dev_guide.rst',
    'dev_guide/platforms/vmware_guidelines.rst',
    'dev_guide/platforms/vmware_rest_guidelines.rst',
    'getting_started_ee/build_execution_environment.rst',
    'getting_started_ee/introduction.rst',
    'getting_started_ee/run_community_ee_image.rst',
    'getting_started_ee/run_execution_environment.rst',
    'getting_started_ee/setup_environment.rst',

    'getting_started_ee/index.rst', (stub page to point to new EE getting started home)

Excludes porting guides and roadmaps specific to the Ansible package:
    'porting_guides/porting_guides.rst',
    'porting_guides/porting_guide_[1-9]*',
    'roadmap/index.rst',
    'roadmap/ansible_roadmap_index.rst',
    'roadmap/old_roadmap_index.rst',
    'roadmap/ROADMAP_2_5.rst',
    'roadmap/ROADMAP_2_6.rst',
    'roadmap/ROADMAP_2_7.rst',
    'roadmap/ROADMAP_2_8.rst',
    'roadmap/ROADMAP_2_9.rst',
    'roadmap/COLLECTIONS*'
9

@samccann Not to take things too far off track but I feel like we should put this through the lens of the migration to Read The Docs.

The goal we want to achieve with that effort is to have a simple, static “one-stop shop” for Ansible documentation. The resulting structure will be like this:

https://ansible.readthedocs.io/en/latest/ # <- Replaces the current "docs.ansible.com" landing page.
https://ansible.readthedocs.io/projects/ansible-core/en/devel/ # <- Built from "ansible/ansible-documentation".
https://ansible.readthedocs.io/projects/ansible/en/devel/ # <- WIP replacement for the current package docs built from "ansible/ansible-documentation".

Moving community guides to their own docsite and repo simplifies the migration and the content fits neatly with this structure. I understand the motivation for having core docs bundled into the package docs as they are now. But I question if that maintenance overhead is still justifiable as RTD can potentially give us a better “one-stop shop” experience. At the minimum we can update the theme navbar with a drop-down menu of project docs to switch between - ideally we’ll be able to create a custom fly-out menu but that might be a bit of a stretch.

Anyway these are just some thoughts but, fwiw, I’m really starting to feel like breaking things up further into separate domains of content will reduce complexity and allow teams to move faster without getting in each other’s way. We don’t need to sacrifice user experience or navigation to do that.

We can also get rid of the need to have a separate repo for the publishing workflow that gets package docs onto RTD.

10

So as I recall, the driving point of having one set of documentation that covers everything (users, contributors/developers, community members etc) was visibility into all the options so to speak. if I’m reading about how to use playbooks, I can see in the left-hand navigation that there is a community I can join… .or ways I can contribute or develop my own modules and collections etc.

The other driving point was search. We need a way to search across different documentation sets if we have them on different docsites so to speak.

That said, I’m not sure what you are proposing here.

Moving community guides to their own docsite and repo simplifies the migration and the content fits neatly with this structure.

That sounds like creating a docsite just with community guides, which was the proposal at the start of the conversation but it’s drifted now to moving them to a separate repo, but continue to build them to the same docsite as the Ansible package (so the package docs don’t change at all from the reader perspective).

Then there is

I’m not sure what this an the other separate domains of content mean here. Can you elaborate with specific examples of where the user guide, deve guide, contributor/community guides would live in these different domains?

11

Hey, I don’t want it to seem like I’m not responding to the questions. I started a big response earlier today but I’m just back from a long weekend and spent a good bit of that time at the beach. All the sun and surf has slowed my brain down considerably so I more or less failed at responding with all the detail.

I think we covered it at the DaWGs meeting today. TL;DR moving to the Read The Docs hosted platform means we can take advantages of their built-in features like cross-project search and version switcher. That allows us to stop having to complicate matters and add work for ourselves with the self-hosted web server. Using the nice bells and whistles with RTD hosting will let us have more smaller, more easily manageable docsites for projects without them being disconnected or difficult for users to navigate between / discover.

Edit to add a link to the DaWGs minutes.