Where should deployment instructions for bundles exist?

[Jorge O. Castro]

I am working on submitting a mediawiki bundle:
https://jujucharms.com/sidebar/search/bundle/~jorge/mediawiki-simple/5/mediawiki-simple/?text=mediawiki-simple

In the GUI we provide a tab called Deploy which autogenerates
deployment instructions. I love this because after editing individual
deploy instructions in charms it's much nicer to have something that
is not prone to human error and will always be correct.

When Matt was reviewing my charm he noticed that I mention "After
deployment you need to...", but the README has no "How do I deploy
this bundle?" -- why would it, there's an entire autogenerated tab for
that!

But the README as a standalone file falls down. For obvious reasons I
don't want to copy everything from the deployment tab into the README.
On top of that when people want to share bundles there will be the
usecase of people passing around just the bundle file without any of
the corresponding documention:

I thought of some ideas, so I thought I could bounce them off the list:

- We could default to the Deploy tab in the GUI.
- We could autogenerate a section on top of the README that points
people more explicitly to the Deploy section.

Also I think it would be worth investigating having the "export
bundle" export everything the user will need instead of just the raw
yaml file. Maybe zip up the bundle and cat the deploy instructions to
the top of the README as part of exporting.

We should also consider adding a comment to each bundle's exported
file to the canonical location of it in the store in case I do get
mailed a bundle with no instructions.

Some food for thought!

-- 
Jorge Castro
Canonical Ltd.
http://juju.ubuntu.com/ - Automate your Cloud Infrastructure