# Managing documentation versions

**URL:** <https://forum.ansible.com/t/managing-documentation-versions/12673>\
**Category:** Ansible Project\
**Created:** [April 12, 2013, 2:12pm UTC](https://forum.ansible.com/t/managing-documentation-versions/12673 "2013-04-12T14:12:26Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![Michael\_DeHaan2](https://avatars.discourse-cdn.com/v4/letter/m/da6949/32.png) [@Michael\_DeHaan2](https://forum.ansible.com/u/Michael_DeHaan2)\
**Post date:** [April 12, 2013, 2:12pm UTC](https://forum.ansible.com/t/managing-documentation-versions/12673/1 "2013-04-12T14:12:26Z")

</div>

Hi everyone,

I have been thinking of snapshotting the documentation.

This is to say [ansible.cc/docs](http://ansible.cc/docs) will always point to the latest, but will have a section for  
“previous documentation versions”.

Something like:

[ansible.cc/docs/](http://ansible.cc/docs/)  
ansible.cc.docs/releases/1.1/\_\_\_

My idea for doing this is that it will be super easy to tell what is available to you, without  
looking for “version added” information in the documentation. It should still be possible to be  
able to accept patches to previous doc versions.

In particular, it will also allow me to showcase 1.2 variables and conditionals and let old-school  
variables/conditionals take a backseat, and also present roles in “best practices” without the qualification that you might not be able to use them yet.

Open to thoughts.

(I also am going to take a stab at trying to integrate the new Angular.js based module docs  
viewer into the module docs, hopefully)

---

<div class="post-metadata">

**Author:** ![Tin\_Tvrtkovic](https://avatars.discourse-cdn.com/v4/letter/t/bc8723/32.png) [@Tin\_Tvrtkovic](https://forum.ansible.com/u/Tin_Tvrtkovic)\
**Post date:** [April 12, 2013, 11:07pm UTC](https://forum.ansible.com/t/managing-documentation-versions/12673/2 "2013-04-12T23:07:06Z")

</div>

I’m definitely in favor of versioned documentation. I find jumping around versions in the official Python docs very useful and not confusing at all, and if I’m stuck with a particular version of Ansible being able to look at only the relevant documentation is useful.

A thing to think about is the amount of cross-version referencing in the docs. For example, the official Python docs will often backreference a previous version (for example a method will say “Added in Python 3.2”, just so you know how recent and well supported something is). I’ve not seen much forward referencing; it’d probably only be worth it in case of serious depreciations, like the new moustache playbook templating in 1.2, and then only for warnings, not verbose information.

---

<div class="post-metadata">

**Author:** ![Michael\_DeHaan2](https://avatars.discourse-cdn.com/v4/letter/m/da6949/32.png) [@Michael\_DeHaan2](https://forum.ansible.com/u/Michael_DeHaan2)\
**Post date:** [April 12, 2013, 11:24pm UTC](https://forum.ansible.com/t/managing-documentation-versions/12673/3 "2013-04-12T23:24:01Z")

</div>

This is about done.

Small request, let’s say “Jinja2 templating” not “moustache” templating, “moustache” is actually another template engine.

Not sure what forward referencing would mean, but we do note “version added” in some places. Part of the reason to split this off was to avoid needing to do that so much, however.

---

<div class="post-metadata">

**Author:** ![Tin\_Tvrtkovic](https://avatars.discourse-cdn.com/v4/letter/t/bc8723/32.png) [@Tin\_Tvrtkovic](https://forum.ansible.com/u/Tin_Tvrtkovic)\
**Post date:** [April 13, 2013, 1:25pm UTC](https://forum.ansible.com/t/managing-documentation-versions/12673/4 "2013-04-13T13:25:50Z")

</div>

By forward referencing I meant mentioning things available in later versions, which normally you’d want to avoid (which is the point of versioning the docs). So in the docs for 1.0, you wouldn’t mention dry-run support at all. But some things you might want to mention; actively deprecated stuff like $vars in playbooks in docs \<1.2 might have a notice like “This is being deprecated in future versions, please see _here_ for the new way”.

You’re right about the “moustache” term of course (I’ve actually considered the official moustache templates for a project), but calling them moustaches is just so cute.

---

<div class="post-metadata">

**Author:** ![Michael\_DeHaan2](https://avatars.discourse-cdn.com/v4/letter/m/da6949/32.png) [@Michael\_DeHaan2](https://forum.ansible.com/u/Michael_DeHaan2)\
**Post date:** [April 13, 2013, 1:31pm UTC](https://forum.ansible.com/t/managing-documentation-versions/12673/5 "2013-04-13T13:31:48Z")

</div>

$vars in playbooks haven’t really been deprecated (they have no plan for being removed), they’ve just been undocumented to encourage usage of the new form.

---

<div class="post-metadata">

**Author:** ![Tin\_Tvrtkovic](https://avatars.discourse-cdn.com/v4/letter/t/bc8723/32.png) [@Tin\_Tvrtkovic](https://forum.ansible.com/u/Tin_Tvrtkovic)\
**Post date:** [April 13, 2013, 1:39pm UTC](https://forum.ansible.com/t/managing-documentation-versions/12673/6 "2013-04-13T13:39:17Z")

</div>

Ok. At a certain point something will get deprecated or removed. These are the things that might get mentioned in older docs.