Hi everyone,
I have been thinking of snapshotting the documentation.
This is to say ansible.cc/docs will always point to the latest, but will have a section for
“previous documentation versions”.
Something like:
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)
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.
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.
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.
$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.
Ok. At a certain point something will get deprecated or removed. These are the things that might get mentioned in older docs.