mbruzek
commented
8 years ago @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
marcoceppi
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 INTERFACEPATH 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.