chef-provisioning `getting started` guide spike

[tyler-ball]

We need a better story around 'getting started'. There are currently some docs in chef-provisioning but word on the street is they don't work. So this spike is to examine where we are currently and discuss where we want to go.

Acceptance Criteria: Write down 3 stories, each of which encompases a different step in the 'getting started' guide. The first step should be prerequisites and creating a machine locally with vagrant. The second step should be creating a single machine in AWS. The third step should be creating a cluster of machines with a load balancer and back end database with chef-provisioning.

All the guides should be written in a walkthrough oriented, blog style format which allow users to go from nothing to a completed product at the end of the post.

Questions:

• [ ] Where do we want to store the guide? What format will it take? I propose in a README for now until we can get space in the docs site for it.
• [ ] Collect a list of existing starter guides in other blogs that we can tag as outdated and start redirecting to our guide.
• [ ] Should we have downloadable or generatable cookbooks as part of this? Or just rely on instructions on the page?
• [ ] What do the current docs look like? Can we just modify them to fit our needs, or do we need to start from scratch?

[bookshelfdave]

probably out of scope, but I'd love to see this as part of Learn Chef.

[georgecook-cbt]

It might also be useful to have a bit on extending current driver coverage for folks who want to help add more services. I was thinking about how you were discussing in the video about the differences in the aws resources and how they're extensions of one of the two base resources.

[jamescott]

We have solid reference topics for all of the machine resources:

http://docs.chef.io/resource_machine.html http://docs.chef.io/resource_machine_batch.html http://docs.chef.io/resource_machine_execute.html http://docs.chef.io/resource_machine_file.html http://docs.chef.io/resource_machine_image.html

^^^ these should be reviewed for accuracy, with examples added (if possible).

Docs are weak in the following areas:

Driver references Overview (what is it, diagrams, use case/scenarios) Getting started load_balancer resource

We should make sure that if we blog about these features/components, that the docs have all the info first, so that we can link from the blog to the finished topics.

There is a topic for Provisioning, here: docs.chef.io/provisioning.html ... right now, it's a list of all the provisioning-related resources (including all of the Cheffish ones). As the docs for provisioning improve, they should be made visible via docs.chef.io/provisioning.html, as that's intended to be the main doc page for Chef provisioning similar to docs.chef.io/kitchen.html is for Kitchen.

james

[jamescott]

well, put the machine_batch resource in the "docs are weak" list, as it's missing descriptions for many actions/attributes.

[bookshelfdave]

awesome, thanks @jamescott

[jamescott]

Baseline AWS driver-specific resource references:

http://docs.chef.io/provisioning.html#aws-driver-resources

[georgecook-cbt]

That's some good looking doc!

[tyler-ball]

This is partly duplicated with https://github.com/chef/test-driven-infrastructure/issues/23