Official documentation is a few months stale

[msterin]

• Official documentation referred from Readme.md is a few months stale and does not cover admin 'config', things like _VM_DS and _ALL_DS for default datastores, and probably more.
• Documentation release process is broken as there is no way to associate documentation with dev branches so there is no way to manage the doc the same way we manage the code. It is not clear at which point a doc for a new code needs to be reviewed and merged to gh-pages branch. Is it when we merge to master ? Or when we cut a branch ? It basically forces the documents to be ignored until the release.
• There is redundant information in ./docs (which is actually accurate bit not referred from anywhere) and all process is error prone

We need to do the following:

• have the web site content caught up to actual state of the code.
  • git diff [master]docs/.. between the moment gh-pages was updated and now
  • Manually apply the diff to proper .md files in gh-pages. Since the files layout has changed , it has to be a manual process. The good news is that we've been focusing on test automation lately so there are not many change to the docs.
• have ALL docs in the same branches with code (i.e. master).
  • I suggest docs/external/_all_stuff_we_need_for_doc_site_including_actual_content. We can keep docs/internal for specs and the likes (tracking at Rearrange markdown files #1865)
  • move current docs/* to docs/internal and remove stuff redundant with docs/external (e.g. userguides)
  • create a new branch off master for adding all stuff from gh-pages there, probably under docs/external, and when done merge it back to master (standard process)
• drop gh-pages branch and forget it as a nightmare (can delete the branch after the stuff is in [master]docs/external
• update Contributing.md to point to doc files which need to be updated when the code is updated, and in the same branch
• update release process to generate external web site from [latest_tag]/docs/external
• optional: add http://vmware.github.io/docker-volume-vsphere/documentation/latest web site which updates nightly from master. Keep http://vmware.github.io/docker-volume-vsphere/documentation or http://vmware.github.io/docker-volume-vsphere/documentation/stable web site as the one which updates on release, from the tagged source. (being tracked at [Doc] Allow user to navigate through older release notes #1759)

//CC @pdhamdhere @lipingxue

[pdhamdhere]

CC/ @tusharnt

[tusharnt]

CC @girishshilamkar - we need to address this for vDVS ASAP.

[tusharnt]

Issue #1545 tracks the action item to fix doc release process.

@shuklanirdesh82 to file separate issue for the following

• Layout of docs folder needs to be revisited.