unversioning some documentation guides

[samccann]

Summary

Problem

Today, we have multiple files that we only maintain in /devel/. Historically, we had problems keeping these files up to date in other branches (latest and older). The docs team chose to publish the following pages only to devel and put a stub page up in latest and earlier releases to point to devel:

• Porting guides
• Release and Maintenance

While this has worked well to keep the relevant docs current, it can be a cause of confusion. One recent reader was confused that we were pointing them to a devel page which has the banner that says this is not a guaranteed stable branch.

We have another set of guides (the community and contributor guides) that are getting a significant overhaul in devel. These guides are not specific to any release (core or Ansible package), but because we publish only to versioned urls, we force these guides to be 'versioned'.

Possible Solutions

Three solutions come to mind:

1. Publish only to devel only.

This would follow the process we use forthe other unversioned pages and stub out earlier releases to say 'go to devel'.

pros
Simple, no backports required. Works well for pages that update frequently (which these guides are at the moment).

cons
Same confusion for readers - Can they trust a docs page that says 'not guaranteed stable'? We currently have no way to modify
the banner per html page.

2. Publish as versioned

This would publish the guides to devel and require 'someone' to track all updates in devel and backport to current releases.

pros
The doc version that gets the most traffic (latest) with have up todate information.

cons
This didn't work the last time we tried keeping things in sync and we had more people involved to help at that point. If we choose this option, then the docs lead will have to spend more time managing backports and less time on anything else.

Time estimate: 2-4 hrs a week depending on level of changes to affected pages.

3. Create an unversioned docsite and publish there

This option would create, for example, docs.ansible.com/community.index and publish community guides there.

pros
Publishes what they really are - guides not tied to any release.

cons
Search will not currently work to find 'contributor guide' content on docs.ansible.com/ansible. We could keep a stub page on the left-hand navigation to direct readers where to find information on contributing to Ansible. That is a partial help in that the reader still sees a 'contributing' section in the left-hand navigation. But the search problem remains. If for example the reader searches 'ansible on matrix' to find out where we chat, they would not get any result because that information is now on docs.ansible.com/community.

[acozine]

If we moved the source files (the .rst files) for this specific content into a separate repo (maybe something like ansible/unversioned_docs), could we pull them in on the latest build using code in antsibull? This would solve the problem of users being scared off by the "not stable" warnings without forcing a bunch of backports.

[mariolenz]

One recent reader was confused that we were pointing them to a devel page which has the banner that says this is not a guaranteed stable branch.

Make this two. I'm also confused about this. I always think: Does this really apply to the stable version I'm using at the moment? After all, there might be something different difference in devel. It's a bit irritating.

[felixfontein]

One downside of "publish to devel only" is that for every stable branch creation, you have to 'clean up' the newly created branch by removing copies of these documents, and instead replace them with documents pointing to devel. The other approaches do not have this problem.

I'm somewhat tending to 3 (unversioned docsite), and I would definitely have references to it (and stubs) in both devel and stable docs.

[felixfontein]

If we moved the source files (the .rst files) for this specific content into a separate repo (maybe something like ansible/unversioned_docs), could we pull them in on the latest build using code in antsibull? This would solve the problem of users being scared off by the "not stable" warnings without forcing a bunch of backports.

I don't think antsibull should (or needs to) be involved in this. This should be done as part of the ansible docs build by code in https://github.com/ansible/ansible/tree/devel/hacking/build_library/build_ansible/command_plugins (if actual code is needed).

[felixfontein]

For 'publish as versioned': here a bot could help that automatically creates PRs once the copy of these files in stable branches no longer matches the one in devel (and pings the docs team). Not sure who wants to write and maintain such a bot, though :)

[samccann]

Closing this one - I've been keeping latest/devel in sync for the past couple of releases so the 'devel only' docs confusion is gone now.