---
# System prepended metadata

title: How to handle unversioned documentation
tags: [Documentation]

---

# How to handle unversioned documentation
###### tags: `Documentation`

## 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](https://docs.ansible.com/ansible/latest/porting_guides/porting_guides.html)
* [Release and Maintenance](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html)

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.

note - developer guidees must remain versioned as a collection creator needs to understand the differences between ansible-core 2.14 and ansible-core 2.12 if they plan on supporting a range of core releases.