Versioned documentation

[dharmabumstead]

Proposal: Docs Versioning

Author: Scott Butler <@dharmabumstead>

Date: 2017/03/24

• Status: New
• Proposal type: documentation
• Targeted Release: 2.4
• Associated PR: no PR; https://public.etherpad-mozilla.org/p/ansible-versioned_docs
• Estimated time to implement: TBD

Motivation

This will make it easier for users to find the appropriate documentation for the version of Ansible that they're using, and will explicitly specify which docs are supported, which are archived, and where they can be found.

Problems

We currently don't have a clean, clear system in place for publishing multiple versions of the documentation and for archiving old documentation so customers can find it.

Solution proposal

• Doc sources (module and non-module) live in the git branch with the specific version of Ansible (as now).

• During the doc build, doc version is pulled from 'VERSION' and added to the header and footer of each generated page, along with a message like "This is an out-of-date version of Ansible. For the latest version, go here" along with a link.

• Doc version is also part of the page URL for the generated HTML. Example: https://docs.ansible.com/ansible/2.3/intro_networking.html

• The url 'ansible/latest/*' always redirects to the current stable release of the docs.

• Doc support for backported bug fixes and updates is strictly limited to -1 and +1, as discussed: previous version, current version (stable), and devel.

• Older doc versions are archived on the day the new version that pushes them off the end of the 'supported' queue is released. Archived docs are accessible through a 'doc archives' link somewhere in the docs and on the doc landing page. 'Archiving' consists of making a zip/tarball of that version's HTML directory and storing it, and also - arguably, possibly - just leaving the HTML directory intact with a clear message saying something like 'This is an unmaintained archival snapshot of an old version; please see here for the current version'.

Dependencies (optional)

Testing (optional)

Documentation (optional)

Anything else?

[abadger]

• We should also have a url that always points to the latest devel build. ansible/dev/ or ansible/devel Seem like they would work.
• My personal wish for "archiving" would be to just leave the HTML up for people to browse (with the header saying that the documentation is for an out-dated-version, I don't share bcoca's hesitation about this) and not bothering with tarballs.
• If there is a value add to having tarballs of the documentation, maybe they should be created when the documentation builds, rather than at an archiving date? That way people can always have the choice to download the documentation in a tarball if they want.

[alikins]

+1 to proposal + abadgers comments about '/devel' and leaving versioned html up.

[bcoca]

+1 on devel -1 on tarballs, my view was always deleting the older versions, not zipping them up.

[gundalow]

+1 to ansible/devel (not dev), we should be consistent with the branch name -1 to tarballs

I don't believe there is any risk of leaving older versions of docs up, however if we do end up deleting older versions it may be useful to have a redirect from ansible/2.1/* to a static page that says these versions are not support and docs have been removed, rather than just a set of pages that 404s

Can we do anything so Google Search prefers ansible/latest/

Will search be versioned?

Implementation question: In Jenkins will this exist as on job type per branch?

[docschick]

For consideration:

1) For Swiftype search (the docs search engine), you may want to add meta tags to the docs to rank/weight the searches to show up with the most current/most stable search results first. for example:

I added this in layout.html for Tower docs, right under the header, near the Adobe tracking info. It needs to be updated with the published_at date (year/month/day) for each major release. Swiftype will also need to be "recrawled" for the ansible core search engine when these doc releases for versioned docs happen (at the time of each new, versioned release). (I can help with this if needed or I can help get someone else up to speed on it.)

2) For SEO considerations, you may want to add a canonical link to point to the docs that you want to show up as the "latest" version in Google searches for example: <link rel="canonical" href="http://docs.ansible.com/ansible-tower/latest/html/installandreference/index.html>

I added this in layout.html for Tower docs, right under the header, near the Adobe tracking info. This is still a work in progress for Tower docs. If this is an option you want to explore, let me know and I'll update you on the full process we are undertaking to make this work properly.

3) I like the idea of leaving an HTML directory intact for archived versions. Another option could be the way we handle the links to archived HTML docs in Tower (a menu of archived links that navigates directly to the version the user selects).

4) Shane MacDonald created an image that contains only the dependencies required to build the docs for Tower... if this can be leveraged for core needs, please feel free: https://github.com/ansible/product-docs/pull/82/commits/63e3e70c055516f5fd32dda1369a389783e6d123

[jctanner]

+1 shipit LGTM

[sivel]

+1

[nitzmahone]

Also +1 overall, +1 to static devel (and probably "latest stable") URLs, -1 to doc tarballs (just keep HTML output)

[mattclay]

+1 overall +1 to devel and stable entries -1 to doc tarballs

[gundalow]

@docschick Thanks your comments, that address all of my concerns. FYI the core docs are currently built via Jenkins on whatever slaves are behind that. Currently each

Discussed in Core Meeting 20170228 Agreed:

• Only X.Y (not X.Y.Z)
• No RCs
• /devel/ (not /dev) (no X.Y for that release)
• /stable/ (not latest, to make it clearer what thisis)
• Static HTML + "unmaintained" banner for unmaintained versions
• External search engines to ignore (robots block?) everything but /devel and /stable/
• No need to tarball
• older HTML can stay live forever. it will have the banner

Question to people that understand things better than us:

• Should `/stable/' be a 302/symlink to

[docschick]

@gundalow Tower docs are also built via Jenkins. With help, we setup a way to build/push different versions as official/production-ready without writing over the main symlinks that should point to the latest version of the docs.

[gundalow]

That sounds cool.

I think Core team have finished discussing this, so I'll hand over to @dharmabumstead and @docschick to review. Thanks.

The Community (and Core Team) are looking forward to this, should make a massive difference.

[gundalow]

OFFICIALLY APPROVED (Core Meeting 20170228)

[dharmabumstead]

w00t!

[gundalow]

It would be good for the following directories to always point to devel

• /dev_guide
• /community
• /roadmap https://github.com/ansible/community/issues/239

To clarify

• docs.ansible.com/ansible/(dev_guide,community,roadmap) -> docs.ansible.com/ansible/latest/$DIR
• docs.ansible.com/ansible/x.y/(dev_guide,community,roadmap) -> docs.ansible.com/ansible/latest/$DIR

Also http://docs.ansible.com/ansible/community and http://docs.ansible.com/ansible/roadmaps return 404 Adding in /latest/ makes these urls work. This may be caused by the same issue that @shanemcd fixed for dev_guide

[gundalow]

@bcoca suggested moving the source files to make this easier to manage, docs/docsite/rst/SOMETHING/{dev_guide,community,roadmap,etc}

[dharmabumstead]

Implemented. Closing.