Documentation Report: Ansible docs need clearer version management #10967

Closed
duncanawoods opened this Issue May 9, 2015 · 12 comments

Projects

None yet

9 participants

@duncanawoods

Issue Type:

Documentation Report

Ansible Version:

ansible 1.9.1

Ansible Configuration:

Vanilla install from apt

Environment:

Ubuntu 14.04 x64

Summary:

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.

Suggestion:

  • http://docs.ansible.com should contain links to documentation bundles for each major release, not just the current github head. Only publishing an evergreen version with no version number that does not match the latest released version is painfully misleading.
  • Each documentation page should clearly state the release version it applies to. If you stumble across a documentation page from a different version, it should be easy to spot this.
  • Each documentation page should include a change log describing the breaking changes between versions and how to upgrade between them.

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:

  1. Follow http://docs.ansible.com/intro_installation.html to install latest ubuntu version from apt
  2. Install pip from apt
  3. Install dopy from pip
  4. Follow http://docs.ansible.com/digital_ocean_module.html example 2 to create playbook with a task to create a droplet
  5. Docs state "new in version 1.3" great, this implies it should work in ansible 1.9.1
  6. Docs state "using do api version 2" great, this is what I want
  7. Run ansible-playbook

Expected Results:

A new droplet is created

Actual Results:

Depending on how you supply the api_token, your error might be

unsupported parameter for module: api_token

Or

ValueError: invalid literal for int() with base 10: 'nyc2'

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!

@nathanleclaire

I just got bit by this (I'm trying to learn Ansible). +1

@dgtlmoon

+1 Just lost hours to this!

@jimi-c
Member
jimi-c commented May 11, 2015

Hi, sorry for the inconvenience here. That parameter change should have been marked as version_added: 2.0, as it is not in the 1.9 branch at this time. This is partially due to the fact that the module was modified quite a bit for the new DO API, so some parameters were removed and others were added. The Notes section should also be more clear about this (and I will update the docs for now to state this).

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 site-packages/ansible/modules/core/cloud/digital_ocean/.

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!

@jimi-c jimi-c closed this May 11, 2015
@dgtlmoon

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

@jimi-c
Member
jimi-c commented 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 ansible-doc digital_ocean will show you the correct documentation for your installed version.

@duncanawoods

@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...

@khomco
khomco commented Aug 24, 2015

I get the following:

msg: unsupported parameter for module: api_token

What am I supposed to do? I don't necessarily see the solution in this issue dialog.

@duncanawoods

@khomco it means you have a mismatched version of ansible vs. the docs. Follow the ansible installation instructions for installing from source rather than from a package manager and then following the docs should be correct and you will no longer get this error.

@ReservedDeveloper

+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.

@kongdigital

+1

I'm a newcomer and just lost hours to this problem.

@auvipy
auvipy commented Nov 17, 2015

+1

@betrcode

If this is closed, is there a reference to a open issue where versioned documentation is the aim?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment