Review comments on creating charms with layers

[ktsakalozos]

In http://localhost:8000/en/getting-started.html the video is not correctly aligned

The following are for page: http://localhost:8000/en/authors-charm-building.html

• Second paragraph needs rewrite. It is huge! "Layers let you build on the work of other charmers, whether that work is in the form of other charms that you can extend and modify, interfaces that are already built for you and know how to communicate with a remote service and let you know when that service is ready and what it provides for you, or partial base layers that make managing dependencies much easier."
• In "Preparation" we have "So, if you haven't set those up yet, use the previous links to do so. For example:". I can live with that but it is a bit dangerous. What would happen if the setup described in the "previous links" changes? We will endup with wrong instructions.
• This link http://interfaces.juju.solutions/ does not offer much to the reader. I would be nice if we could link to the actual documentation of the interfaces.
• "so the layer we will use is the apache-php5 layer" do not repeat "layer"
• "This is a "runtime" layer" I would prefer the runtime to be actually a link to a description of the layer types.
• "The README, icon, and copyright file will be the same." Will be the same to what? Do you mean will not change so we do not have to define them? Will we "inherit" them from another layer? The same for "The metadata.yaml will be the same except". This "same" is unclear.
• This is a problem I had when reading the walkthrough: "You'll notice that the MySQL relation is passed in so that you can easily access the database connection information." The code at hand is this:

@when('apache.available', 'database.available') def setup_vanilla(mysql): pass

Why is mysql param passed here? It has to do with the reactive layers. Can we make sure this is crystal clear and give appropriate links? eg http://pythonhosted.org/charms.reactive/

• Why are reactive charms documented in their own seperate site http://pythonhosted.org/charms.reactive/ ? This does not add to the consistency of the product.
• Again we need some link to the documentation of layers or else statements like "By setting the apache.start state, we are letting the apache-php layer know that we have finished configuring the application and it is ready to start." look like black magic. How would I know I need to set this state to send this singal to the apache-phph layer?
• After finishing the tutorial with: juju deploy mysql juju deploy local:trusty/vanilla juju add-relation mysql vanilla juju expose vanilla

On my local environment I was thrown to the vanilla admin page where I had to put (among other) database username/passowrd. Rather unexpected since I never set the credentials of the db anywhere.

[lazypower]

Thanks for the feedback @ktsakalozos.

I notice you reference the authors-* document(s) above. These are the docs we are looking to depreciate with the newer developer-* docs. The layer's bits were added on monday and perchance may have not been ready when you were doing the review.

If you get a chance, can you contrast/compare the reimplementation of the building/layers docs and see if we have committed potential ambiguity in our re-telling of the narrative?

Thanks!

[lazypower]

To clarify, this wont resolve the vanilla demo issue, as the example needs to be updated to ensure we're properly templating the MySQL relationship vars in the vanilla config files. We discovered this directly after the pastebin of the above feedback