Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Documentation Report: Ansible docs need clearer version management #10967
Vanilla install from apt
Ubuntu 14.04 x64
The instructions on http://docs.ansible.com do not match the latest release, will mislead a new user and fail to instruct them to create a working digital_ocean playbook.
The reason is that the docs are unversioned, track the github head and do not contain information about breaking changes. If you install the latest released version from a package manager, you cannot read a compatible version of documentation on the ansible site.
For example, the current digital_ocean module page states "new in version 1.3". This implies that the documentation is compatible with any version more recent than 1.3 but because there are undocumented breaking changes which mean that parameters like region_id have changed type and have new expected values, the whole documentation page is terribly misleading.
Steps To Reproduce:
A new droplet is created
Depending on how you supply the api_token, your error might be
The remedy is to run ansible from the head source version and then following the documentation will be valid but it seems deeply ironic for a configuration management tool not to not let its users be strict about versioning!
Hi, sorry for the inconvenience here. That parameter change should have been marked as
If you would like to start using the new module version in 1.9.x, which matches the docs, you can download it from the git repository and replace your version of digital_ocean.py in
Beyond that, we have had plans internally for a couple of weeks to start offering two versions of the docs - stable and devel, which will track the current stable release and the devel branch to allow for more clear documentation, especially in cases like the above where a major change took place. Keep an eye out for this in the near future. Because of this, we're going to go ahead and close this issue for now. If you have any further questions regarding our docs plans please feel free to start a thread on one of the project mailing lists (preferably the ansible-devel list):
Thanks, and sorry again for the confusion!
I just checked http://docs.ansible.com/digital_ocean_module.html and I don't think that 'closed' addresses this issue - there's still no clear indication that this is for 2.x API and wont apply to us Ubuntu users who are on 1.9.1
"region_id | This is the slug of the region you would like your server to be created in."
this is infact not true
referenced this issue
May 12, 2015
@dgtlmoon I closed this because the reported issue was about process, and not necessarily the mistake in the DO module docs. Due to the fact that the module changed significantly in devel, I'm leaning towards correcting that via the doc split I mentioned above. I will put a note in that doc though, to mention the change and that using
@jmi-c how about only closing this once the stable docs have been released? As it stands, neither the specific digital ocean issue nor the general versioning issue have been resolved and new users will continue to lose time. The intention is great but if I closed all the things I intended to do...
+1 on this issue, and agree with sentiments to not close until stable docs are released. From a newcomers perspective, a large part of the appeal of Ansible is the ease of ramp up and the thorough documentation. Not being able to trust that documentation definitely makes it difficult to sell.
To be fair, the docs have been updated to reflect the 2.0 nature of this feature. However, I suspect many tend to work top down, and may not get to that particular part of the document until after hitting several walls trying to get examples rolling from above sections. Perhaps something to chalk up to RTFM, but there it is.