Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
SoC vs. Juju Dev Docs #41
Comments
|
@justcfx2u Thank you for the detailed review and feedback on the docs! The over linking is my fault. When I write I err on the side of too much information. I now recognize that the links may not be helpful for many types of people. I will work on making this better, and like your idea of creating a link section at the end or something like that. We did not have a hello world example charm (written in reactive). The vanilla example should not fail. We will fix that issue and look for a simpler example. We like the vanilla charm because it has one relation to a database, charms that have no relations are not really useful in the ecosystem. So for the balance of education and usefulness vanilla won, but to your point we would like to have a simple example that gives the readers something to accomplish. Other authors already fixed the typos on the environment variables and we will work on making these docs better and look into all your suggestions here. Thanks again for the time it takes to read and comment on the documentation. We want to improve and can only do so with impartial, and detailed comments such as this. I really appreciate the feed back and aim to do better in the future! |
justcfx2u
commented
Dec 10, 2015
|
Thank you for such positive feedback. As you seem to be genuinely interested in more, I tackled the next section. Standard disclaimer: These are impulsive thoughts, recorded at the time of initial reading by a newcomer. I may be wrong or misdirected or assume the wrong things. But it is my hope that they will be useful in this raw format. Please do with these suggestions as you will. Event Cycle Keep just the Charm Hooks link. :) _Deployment Events by example_ "When deploying a charm..." At this point in reading, I'm not sure what the Charm lifecycle stages are. I want to be able to look at a small flowchart. I don't even necessarily care what goes into it, or at what detail level. I just sort of want to visualize how a charm is deployed, lives, and is cleaned up. Maybe have a corresponding 'development' lifecycle outline/flowchart, everything from git cloning a layer to basic steps common to all layers (e.g., incl. proofing a charm), adding it to a local/remote repository, through to (and referencing) the remainder of the lifecycle (deploy, live, cleaned up/undeployed). "... basic series of hooks executed in the initial deployment cycle". The word 'initial' implies that there can be a subsequent deployment cycle for the same charm in some way. But aren't the hooks listed for EACH charm deployment, no matter what? It is also not explicitly said if the listed hooks are GUARANTEED to run, and if they are guaranteed to be run in that order. It is easy to assume all of the above, but I don't want to guess. :) _Configuration Events by example_ "vanilla charm", maybe make this a link to the previous section? "[...] Vanilla charm (per our previous example)" might shape up the sentence a bit, especially if it is linked. Perhaps also give an example of what exactly would be needed to "change the configuration of the vanilla charm". When reading this I want to go try it right away, to trigger this config-changed hook. I also want to know how to observe that the hook has actually been triggered; where would I go, and what would I need to do to see the logs/ensure that this action occurred? "When a relation is added from the vanilla charm to a database charm, the first event is database-relation-joined [...]" WHY is it specifically _database_-relation-joined? A reminder of exactly the syntax used to create the relation would be well-paired with a very terse explanation on how the system determines what a relation should be. As of this reading, my understanding of the situation may be that: Hypothetical explanation/clarification follows:
Also, is it possible to have multiple providers vs. required interfaces be satisified with a single command? For example, Will ' Tempted to follow the link 'creating a charm in the reactive framework' but I don't think I know enough at this juncture... :) "We will preserve the install and config-changed hook(s) in most layers." -- what? Preserve? From what destructive force? We're talking about layers again, but now I'm thinking layers are potentially destructive to other layers in some way, and now I'm not sure how layers relates to Reactive, exactly. "The relation hooks are generated when using an interface layer, during the charm build process." Maybe:
It seems that Charm Layers and Interface Layers are covered _after_ this section, so baseline terminology has not yet been established. If the Table of Contents will not be rearranged, maybe a hover-over/dotted underline/tooltip, or sidebar to give a 1-sentence brief about these may be appropriate. "The remainder of actions taken, will be directed with artificial states, set by the layers author." -- unnecessary commas? _Handling reactive states_ "When charming..." has "charming" been defined? It is a casual term, which is fine. It seems to be the 2nd usage of the term, but a formal "using the Juju charm framework/ecosystem/writing Juju charms (commonly referred to as simply 'charming')" or something might do well here. Is 'reactive framework' really 'Reactive Framework' or 'Reactive framework' in disguise? :) "When charming with the reactive framework, it’s possible to use developer created states and boolean logic to run code when the states represent something meaningful to your deployment. Such as when a database is connected, and when it is available, or the primary workload becoming available for use. These are additional “events” that are abstracted from the hook event cycle outlined above." might become:
"When building a charm using layers, that implements an interface layer - these layers set states for the code to react to. This allows the charm author to focus solely on the states rather than the traditional method of putting all the code in the relationship hook sequence." might become:
What are the relationships between 'traditional, hook sequences' versus states? This document is currently assuming a priori knowledge of how things were done without layers. This is not the case as a first-time reader trying to learn about 'Charming 2.0'. "In the vanilla layers.yaml file, we include “interface:mysql"." Code block snippet, please! I'm too lazy to alt-tab to my terminal, I just want to keep reading... "This relates directly to the “database” relation defined in metadata.yaml - with this inclusion in layers.yaml your charm will pick up the mysql interface layer from the layers webservice." I only sort-of understand this.
"It’s important to note that the instructions for this particular interface ..." "Interfaces are unique to the author’s implementation, and any states set will vary from interface to interface." Consider moving this sentence WAY up toward the front of the document. :) "These states are documented in the interface layer repository README.md file." might become:
|
justcfx2u
commented
Dec 12, 2015
|
_Charm Layers_
_Base, or Runtime, Layers_ "The most basic example is just that, layer-basic. It provides nothing more than the minimum needed to effectively use layered charms: charms.reactive, charmhelpers, and the skeleton hook implementations that call into the reactive framework. However, the most useful base layers are actually a type of runtime layer. For example, layer-apache-php provides Apache2 and mod-php, as well as mechanisms for fetching and installing a PHP project within that runtime." Delete "However," and split into a new paragraph:
_NOTE:_ Dead link, 'layer-basic' yields GitHub 404. Was it renamed to reactive-base-layer? "Base layers can be written in any language, but must at a minimum provide[1] the reactive framework that glues layers together, which is written in Python. This can be done trivially by building the base layer off of layer-basic." [1] "Provide"? If I were attempting to write in bash, how would I "provide" the reactive framework? "Interface layers are perhaps the most misunderstood type of layer, and are responsible for the communication that transpires over a relation between two services. This type of layer encapsulates a single “interface protocol” and is generally written and maintained by the author of the primary charm that provides that interface. However, it[1] does cover both sides (provides and requires) of the relation and turns the two-way key-value store that are Juju relations under-the-hood into a full-fledged API for interacting with charms supporting that interface." [1] "It"? Maybe, "Interface layers do cover..."? "It is important to note that interface layers _do not_ actually implement either side of the relation. Instead, they are solely responsible for the _communication_ that goes on over the relation, relying on charms on either end to decide what to do with the results of that communication."
Add emphasis. "Interface layers currently must be _written_ in Python and extend the ReactiveBase class, though they can then be _used_ by any language using the built-in CLI API.[1][2]" [1] Tell me more! Link to a Python (preferred) example of using an interface. Link to a CLI API example. [2] Maybe spell out CLI -> "command line" and mention which program/utility actually does this. S3 Access Denied when attempting to click Developing Interface Layers: (https://s3.amazonaws.com/juju-dev-files/docs/en/developers-interface-layers.html) Lowercase 'reactive' is as confusing as 'vanilla'. Change it to be a proper noun (or merely a disambiguated one) instead of regular-looking adjective? "Building on base and interface layers, charm layers are what actually get turned into charms. This is where the core logic of the charm should go, the logic specific to that individual charm. This layer brings together all the pieces needed to create the charm. It is where most of the charm’s config options will be defined, and where the reactive (framework) handlers that do the specific work of the charm will go. It will need to contain the charm’s README, copyright, icon, and so on." "Charm layers should be the most common type of layer, and is what most charm authors will be dealing with. However, the goal is to keep them[1] focused on just that specific charm’s logic and needs, and to push any commonality into an appropriate base layer. Charm layers should contain as little boilerplate as possible." [1] "Them"? Charm authors or interface layers? "Charm layers can be written in any language, and there are helpers for writing them in Bash." Add link to examples? "For languages other than python or bash, [do things] using [this utility/mechanism/command-line (and where/how to use it within a charm)]." "States are synthetic events that are defined by the layers author. States allow for the layer, or related layers to subscribe to these [events][1] and take action only when appropriate. Consider the example illustrated in the Getting Started[2] guide. [The apache.available state][3] is set from the apache-php layer. Any layers built on top of the apache-php layer can subscribe to this state with a @When decorator[4] to take action only after the Apache service has been started. subsequently the @when_not decorator has also been made to assist guarding against running code when a state has been set, which lends itself nicely to idempotent behavior." [1] Edit for consistency. [2] "Getting Started" link doesn't lead where I think it should lead. [3] Clearer/more explicit. [4] Include footnote/reference for other languages. How do they subscribe to states? Or say explicitly that they cannot. "Charmers can set synthetic states:" Maybe 'custom' states? Using the word 'synthetic' makes me want to go into a meta discussion about whether or not programming as a whole is synthetic vs. real. Or perhaps define the difference between a 'synthetic state' and a '... natural(?) state' if such things exist. |
justcfx2u
commented
Dec 12, 2015
|
_Writing a layer by example_ Is developer-layer-example.html linked to from the Table of Contents? Is there a missing discussion on charm proofing and building? There also seem to be missing instructions on checking out a layer and getting set up with it before diving into editing files. |
|
Hello @justcfx2u. Thank you for all the feedback! This is a treasure trove of data for us to work through to improve our docs. I took a shot at incorporating your feedback on the developer-getting-started document here: 283d8fd I hope this is an improvement and resolves some of your issues. Please take a look and let me know. |
referenced
this issue
Dec 15, 2015
marcoceppi
commented
Dec 16, 2015
|
@justcfx2u Thanks for this feedback, it's tremendous and extremely helpful! Over the next week I'll work on breaking down your feedback into actionable issues on the repo to help identify tasks that people can work on. This feedback will make sure when we land these docs onto jujucharms.com they'll be an awesome experience for everyone |
justcfx2u commentedDec 9, 2015
I was asked by @chuckbutler to give some feedback on:
https://s3.amazonaws.com/juju-dev-files/docs/en/developer-getting-started.html
I trust this is the correct place. :)
With apologies up-front, this "issue" is a bit of a stream-of-consciousness. I fully expect to be told to break these into individual issues, but for this first iteration it might be reasonable to collect everything into one bin until it can be sorted.
_I feel as though the documentation isn't written for the ADHD-friendly._
What I mean by this is there are almost immediately in-line links. Following those leads to more and more and more documentation, which makes it easy to lose focus/direction/purpose.
I would like to experiment with having links be as footnotes, or perhaps not links at all! Perhaps some note to defer to 'Related Links' at the bottom.
A practical example is the very first link: it encourages you to have Juju installed. But the installation document has the user attempting to bootstrap an environment (which defaults to AWS), but information about using the local provider is a couple sentences later (in the dev doc, completely omitted from the installation doc). It's this sort of deep-distraction that makes things a bit hard to follow.
This might be solved by having the 'installed Juju' and 'tested your setup' links (this opinion applies to all other links in the document as well) be atomic. For example, if I clicked 'installed Juju' I might go and follow it to the point where Juju is installed... but not bootstrapped or configured. But, not knowing WHERE to stop as a newbie before returning to the "Getting Started Developing Charms" document has caused me some grief. A suggestion? Split off bootstrapping into a 'next step'... perhaps stopping even before the 'Configuring' section on the installation page, and creating a break: "After this step, Juju is installed! Continue to the Next Step: Configuring Juju", which itself might mention:
Something to that effect. Just enough information (and cross-references) to keep a newbie's attention focused without getting lost in endless documentation branches.
_Prerequisites and Tools_
It is not immediately obvious what the relation between Charm Tools and Charm Helpers is.
I feel as though the subject is switched very abruptly, and -- because of similar names -- this section is really confusing.
For example, I might add something like:
"After charm-tools is installed, the juju command-line utility will be extended with additional commands to make it easy to create, build, and fetch charms. See juju charm help for more information. (ex. juju charm proof -h)."
That would give a practical example of what installing the Charm Tools does for the user and where to get self-help. It also gives the implication that this step is done. The documentation can then move on to talking about Charm Helpers, which is an entirely different topic -- but currently does not have a separate (sub-)header. Maybe one should be added?
More documentation-tree madness linking to Charm Helpers and its associated documentation. I would almost rather not have any links here, particularly since Charm Helpers does not appear to be used directly anywhere else in the document (as it leads into using 'layers', instead of an example based on creating a charm from scratch using Charm Helpers).
Talking about 'Once the charm is complete....' seems off topic for "Prerequisites and Tools". Perhaps move that paragraph to the bottom of the document?
_Designing your charm_
If I have an idea of my first charm, the document seems to have me going to start drawing when I have no idea of the anatomy of a charm. While there is a fine diagram provided, at this point in reading I may not know enough about the components and terminology, nor workflow (e.g., hooks) to design anything effectively. Perhaps this is a simple understanding and a re-titling of "Designing your charm" -> "Design of our example charm" might keep the user in a mode of 'okay, follow the tutorial, worry about my OWN design later'. And with that, perhaps change references from 'your' to 'our', implying the document is building something mutual, that the reader is guided on a pre-set path, rather than encouraged to try applying unique designs immediately.
_Writing your Charm_
Again, as a guide... maybe "Writing the Charm".
An important consideration for me here is... what if I don't _want_ to use layers? At this point I am obsessed about the immediate payoff to make sure I'm doing things correctly before getting more complex. Before... adding layers, as it were.
I feel as though I need to be able to write a 'Hello World!' charm in like 3 lines of code. The documentation should provide me a minimal set of files and configurations (in both bash and Python formats), using as few tools and dependencies as possible (though perhaps with Charm Tools installed), something which will deploy a charm that creates a file on the filesystem /tmp/helloworld for example and can terminate. For a daemon example (since Juju appears to be service/daemon oriented), perhaps a Python-based tcp echo server. Something as bare-bones as possible.
In essence, I don't think I know enough anatomy about a charm, what set of minimum requirements it needs, and how it interacts with its environment before trying to get feet wet with actually creating one. If this is covered in other parts of the documentation, here a link WOULD be handy! But I suspect, since this is the 'developer-centric' portion of the documentation, it may be worthwhile discussing this from a developer's perspective.
There appears to be a typo, at minimum. And perhaps not quite enough has been 'export'ed.
should maybe be:
note in particular the INTERFACE_PATH variable typo fix.
Interestingly, when trying to execute the demo deploy of vanilla, it fails pretty hard:
I'll have more to contribute (read: fuss over) once this issue begins iterating.