Consolidate user documentation for ADB into this Repo

[bexelbie]

User documentation for adb-utils and vagrant service-manager will moved into this repository. This is based on the belief that users of the ADB are the only users of these tools/components.

As a part of this, user documentation will be separate (by directory structure in this repo) from developer docs for extending the ADB. Additionally, all docs will be moved to asciidoc.

Linked issues in other repos:

• adb-utils: https://github.com/projectatomic/adb-utils/issues/137
• vagrant service-manager: https://github.com/projectatomic/vagrant-service-manager/issues/249

I'd appreciate acks from the appropriate number of maintainers to move this forward.

[praveenkumar]

:+1: , I think that make sense but I still think lets we link README of those repo to here and not completely remove it.

[bexelbie]

@praveenkumar yes, we would link to docs from all places where a user could originate.

[brgnepal]

@bexelbie thats a good idea but does it promotes duplication of data? When you say

Development of vagrant service-manager docs will be there in service-manager repo

Does it mean, if we develop some feature, we will update the vagrant service-manager doc and someone will update same data in unified place?

[bexelbie]

@budhrg no. There will be a single copy of all user/consumer documentation. It will be one place for ADB+VSM+adb-utils. A new feature in, for example, VSM, would be updated in that repo.

Only documentation related to actually developing a component, for example documentation on how to add a new service to VSM, would be in the code repos.

[LalatenduMohanty]

+1 Plan sounds good to me.

[navidshaikh]

I'd appreciate acks from the appropriate number of maintainers to move this forward.

+1

[bexelbie]

This is acked. I am waiting on the ones for VSM and adb-utils. Consolidation will be worked on in early July to coincide with some time for a downstream partner (Red Hat) that wants to contributes docs availability. There is a chance this needs to be a separate repo - I'll keep everyone informed.

[hferentschik]

-1 for vagrant-service-manager. I think having one overarching documentation is a good idea and adb-utils is close enough to this repo to include its docs here (if there is really any, after all adb-utils should be transparent to the user).

When it comes to the Vagrant plugin I don't see which parts can be moved to here. All the information currently in the plugin repo (which is really README and CONTRIBUTING) are important and need to be there. When working with Vagrant plugins or RubyGems in general my first stop is the info in the GitHub repo (also RubyGem points to there). This is where I expect to find relevant info about the plugin. In fact personally I judge a plugin/gem already by its content it offers on the README.

I also don't like the fact that the docs are separated from the code. This makes it even harder to enforce that all user facing changes come with the required doc updates. The pull request adding the functionality would not be self contained anymore and would need to reference another pull request in another repo.

Let's say we get a contributor who wants to fix/add something. What then, do I tell him:" Hang on, please check out this repo as well and some documentation there as well?". That's not how you build a community.

And why do you suggest to move the vagrant-service-manager docs, but not vagrant-registration or landrush?