I went through the tutorial and it looks great. I have some feedback below - just my opinions!
PAGE 1
"conjure-up lets you summon up a big-software stack as a "spell" — a model of the stack, combined with extra know-how to get you from an installed stack to a fully usable one."
I think this risks confusing the user immediately with unfamiliar lingo. I would prefer something like, "conjure-up lets you easily deploy and configure complex big-software solutions on public clouds, private clouds, and developer laptops."
"250G SSD with a separate block device for ZFS. Our recommendation for that device is 100G"
I would add to this: "Note that ZFS is recommended, but not required." This avoids losing the user that wants to try a local deployment, but hasn't configured ZFS.
PAGE 2
As I got into this page I noticed that the tutorial in general does not use the "let's do this together" conversational tone that's recommended in the tutorial guidelines. A nit-pick perhaps, but it would be nice to have a consistent tone for all the tutorials. So for example:
"Once you have completed the conjure-up installation, run the software:" becomes "Now that we've installed conjure-up, let's run it:"
I won't belabor the point with more examples, but it would be nice to apply this tone throughout the tutorial.
PAGE 3
"There will be minor differences between the steps for the various cloud providers but generally consists of steps such as choosing a region and entering the credentials for the cloud provider."
Wording here seems a little clunky, how about, "Although each cloud provider will differ slightly, the required configuration steps will generally include choosing a region and providing credentials."
PAGE 4
"You will see verbose output of the machines being automatically provisioned and the Juju controller will install the requisite charm bundle.
Once the machines are provisioned, you will see a table of their current statuses as the software is automatically configured."
Suggestion:
"You'll see verbose output as machines are automatically provisioned and the Kubernetes cluster components are installed and configured."
tvansteenburgh
commented
7 years ago
I went through the tutorial and it looks great. I have some feedback below - just my opinions!
PAGE 1
"conjure-up lets you summon up a big-software stack as a "spell" — a model of the stack, combined with extra know-how to get you from an installed stack to a fully usable one."
I think this risks confusing the user immediately with unfamiliar lingo. I would prefer something like, "conjure-up lets you easily deploy and configure complex big-software solutions on public clouds, private clouds, and developer laptops."
"250G SSD with a separate block device for ZFS. Our recommendation for that device is 100G"
I would add to this: "Note that ZFS is recommended, but not required." This avoids losing the user that wants to try a local deployment, but hasn't configured ZFS.
PAGE 2
As I got into this page I noticed that the tutorial in general does not use the "let's do this together" conversational tone that's recommended in the tutorial guidelines. A nit-pick perhaps, but it would be nice to have a consistent tone for all the tutorials. So for example:
"Once you have completed the conjure-up installation, run the software:" becomes "Now that we've installed conjure-up, let's run it:"
I won't belabor the point with more examples, but it would be nice to apply this tone throughout the tutorial.
PAGE 3
"There will be minor differences between the steps for the various cloud providers but generally consists of steps such as choosing a region and entering the credentials for the cloud provider."
Wording here seems a little clunky, how about, "Although each cloud provider will differ slightly, the required configuration steps will generally include choosing a region and providing credentials."
PAGE 4
"You will see verbose output of the machines being automatically provisioned and the Juju controller will install the requisite charm bundle. Once the machines are provisioned, you will see a table of their current statuses as the software is automatically configured."
Suggestion: "You'll see verbose output as machines are automatically provisioned and the Kubernetes cluster components are installed and configured."
Thanks again for creating this!