/docs

Rework the getting-started sections of the docs. #1826

Merged
merged 19 commits into from May 10, 2017

Conversation

Reviewers

@evilnick evilnick

@degville degville

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
3 participants
@mitechie @evilnick @degville
@mitechie
Owner

mitechie commented May 2, 2017

  • Make the JAAS the default getting-started
  • Move the old one to a tut-lxd page instead
  • Update the wording and docs on both pages to suit.

ToDo:

  • Add a common "install juju client" docs page that all the rest can copy or
    refer to.
  • Bring the language and links to each of the pages into the same language.
  • Run through the instructions step by step with juju 2.1 and 2.2 and verify
    it's all working properly, update any screenshots.

mitechie added some commits May 2, 2017

@mitechie
(WIP) Rework the getting-started sections of the docs. 
- Make the JAAS the default getting-started
- Move the old one to a tut-lxd page instead
- Update the wording and docs on both pages to suit.

ToDo:

- Add a common "install juju client" docs page that all the rest can copy or
refer to.
- Bring the language and links to each of the pages into the same language.
- Run through the instructions step by step with juju 2.1 and 2.2 and verify
it's all working properly, update any screenshots.
41c671d
@mitechie
Add the start of the install doc page
a065e9b
@mitechie
Owner

mitechie commented May 3, 2017

Added the start of an install doc but honestly I think that the reference-releases doc is really just an install doc like this. Maybe the best thing to do is to combine the two into a single reference-install.html and garden the two together.
@mitechie
Clean up the getting-started and the install ref. 
- I tried to remove the old reference-releases
- Updated the content on the reference-install
- Worked to clean up references to the releases page.
- The general getting-started seems like dupe content only used from the jaas
page.

Some other gardening.
cdcbb91
@evilnick

evilnick requested changes May 5, 2017
View changes

I haven't finished! i thought I would give you something to look at though

src/en/tut-lxd.md
+
+# Getting started with Juju and LXD
+
+[LXD](lxd-upstream) provides an amazing experience using machine containers to be able to
@evilnick

evilnick May 5, 2017

Member

[LXD][lxd-upstream]

@evilnick

evilnick May 5, 2017

Member

This first sentence seems to conflate a number of things and is difficult to grasp. I would suggest something like

You may already know that [LXD] provides an amazing experience for managing lightweight containers. Juju can make use of LXD to provide a cloud-like experience from your local machine - etc etc

Possibly a short bullet list of why you would use it. We don't want to be too wordy in the beginning

@mitechie

mitechie May 8, 2017

Owner

Reworded, thanks for suggestion. I like the phrase "cloud-like experience" in particular.

src/en/tut-lxd.md
+clouds. Using LXD as a method to test, verify, and replicate complex software
+deployments is a powerful tool that every Juju user needs. These instructions
+will get you up and running and deliver the best-possible experience with
+Juju. At the moment, that means using the latest release of Ubuntu with '[Long
@evilnick

evilnick May 5, 2017

Member

Sometimes the markdown parser can choke on links with linebreaks in them. It is pretty much always better to begin a new line for long links, so:

  '[Long Term Support][long-term-support]' (LTS): 
  [16.04 LTS (Xenial)][Xenial-download]
@mitechie

mitechie May 8, 2017

Owner

updated

src/en/tut-lxd.md
+Term Support][long-term-support]' (LTS): [16.04 LTS
+ (Xenial)][Xenial-download].
+
+Our system will need the following:
@evilnick

evilnick May 5, 2017

Member

change of POV. We usually use 'you/your' apart from exceptional cases (e.g. some example charms, which are 'ours')

So, 'Your system will also need the following:'

src/en/tut-lxd.md
+
+
+```bash
+sudo snap install --classic juju
@evilnick

evilnick May 5, 2017

Member

we don't need to install Juju. This is a tutorial on setting up LXD for use with Juju. I think at some point we have to assume that people have actually installed Juju, either from 'getting started or the install page'. We do still need to install lxd and zfsutils-linux though.

Perhaps this could be solved simply by supplying a link to install the Juju client in the paragraph above?

@mitechie

mitechie May 8, 2017

Owner

Since lxd is only going to be ubuntu based atm and we do have the install docs link above I figured that it was safe enough to include here for the sake of completeness.

@evilnick

evilnick May 9, 2017

Member

yeah, but that's how we end up with install instructions on every page. I'm happy to remind people they need to have Juju installed, and link them to were to do it. But we also have to think of how they ended up on this page - this is no longer 'getting started', but a tutorial of something useful you can do with Juju.

@mitechie

mitechie May 9, 2017

Owner

I've updated the text around there.

src/en/tut-lxd.md
+
+```bash
+sudo snap install --classic juju
+sudo apt install juju lxd zfsutils-linux
@evilnick

evilnick May 5, 2017

Member

no longer needs Juju. Also, since we no longer have the ppa line, we should sudo apt update before running this

@mitechie

mitechie May 8, 2017

Owner

Why do we need to update before this?

src/en/tut-lxd.md
+
+You will be asked several questions to configure LXD for use. Pressing Enter
+will accept the default answer (provided in square brackets). Only one answer,
+the size of the loop device in the below example, uses a non-default value.
@evilnick

evilnick May 5, 2017

Member

I don't know if it is worth mentioning, but the default value for the loop device size is now dynamic (it is based on a % of storage available). I think it probably isn't worth it, but what do you think?

@mitechie

mitechie May 8, 2017

Owner

wfm, removing.

@mitechie
Owner

mitechie commented May 8, 2017

Thanks for the review. I've updated based on comments and asked a couple of questions in the review points.

@mitechie mitechie referenced this pull request May 8, 2017

Closed

Replace ppa install instructions with snap #1833

@evilnick

evilnick requested changes May 9, 2017
View changes

Some more replies and notes!

src/en/reference-install.md
+### Centos and other Linuxes
+
+
+Spans enable installing the the Juju client on an array of Linux
@evilnick

evilnick May 9, 2017

Member

Snaps

@mitechie

mitechie May 9, 2017

Owner

ty

src/en/reference-install.md
+The Juju team regularly puts out alpha, beta, and RC releases during a
+development cycle. We encourage users to please test these versions out with
+their workloads and use cases and [file bugs][bugs] if you hit any issues.
+Remember that while in development feedback on usability and missing
@evilnick

evilnick May 9, 2017

Member

comma after 'development'

@mitechie

mitechie May 9, 2017

Owner

ty

src/en/reference-install.md
+wrong, but also for things that have an opportunity to be "more right".
+
+
+## Ubuntu
@evilnick

evilnick May 9, 2017

Member

should be ###

@mitechie

mitechie May 9, 2017

Owner

ty

src/en/reference-install.md
+## Ubuntu
+
+It is possible to install other versions, including beta releases of
+Juju via a snap package. See the [install page][install] for more information.
@evilnick

evilnick May 9, 2017

Member

isn't this a circular reference?

@mitechie

mitechie May 9, 2017

Owner

Heh, I think I copied it from the other page and missed cleaning it up.

src/en/reference-install.md
+```
+
+
+## macOS
@evilnick

evilnick May 9, 2017

Member

should be ###

@mitechie

mitechie May 9, 2017

Owner

ty

src/en/reference-install.md
+
+
+
+## Windows
@evilnick

evilnick May 9, 2017

Member

should be ###

@mitechie

mitechie May 9, 2017

Owner

ty

src/en/reference-install.md
+
+
+
+# Building from source
@evilnick

evilnick May 9, 2017

Member

should be ##

@mitechie

mitechie May 9, 2017

Owner

ty

src/en/tut-lxd.md
+
+
+```bash
+sudo snap install --classic juju
@evilnick

evilnick May 5, 2017

Member

we don't need to install Juju. This is a tutorial on setting up LXD for use with Juju. I think at some point we have to assume that people have actually installed Juju, either from 'getting started or the install page'. We do still need to install lxd and zfsutils-linux though.

Perhaps this could be solved simply by supplying a link to install the Juju client in the paragraph above?

@mitechie

mitechie May 8, 2017

Owner

Since lxd is only going to be ubuntu based atm and we do have the install docs link above I figured that it was safe enough to include here for the sake of completeness.

@evilnick

evilnick May 9, 2017

Member

yeah, but that's how we end up with install instructions on every page. I'm happy to remind people they need to have Juju installed, and link them to were to do it. But we also have to think of how they ended up on this page - this is no longer 'getting started', but a tutorial of something useful you can do with Juju.

@mitechie

mitechie May 9, 2017

Owner

I've updated the text around there.

src/en/tut-lxd.md
+
+## Next Steps
+
+Now that you have a Juju-powered cloud, it is time to explore the amazing
@evilnick

evilnick May 9, 2017

Member

I think this should also be updated to reflect that this is no longer 'getting-started' . Perhaps something like

Now that you have configured Juju to work with LXD images, you can test, tweak, develop and experiment with Juju charms rapidly, easily and without additional costs.

or similar

@mitechie

mitechie May 9, 2017

Owner

Updated with new text.

@mitechie
Owner

mitechie commented May 9, 2017

Thanks, I've updated per the latest review comments.

@evilnick evilnick requested a review from degville May 9, 2017

@evilnick
Member

evilnick commented May 9, 2017

Thanks for the speedy updates. I'd also like @degville to have a look over this in case there are bits I missed
@degville

degville requested changes May 9, 2017
View changes

Thanks for these updates @mitechie. I've left a few of my own comments inline, mostly referencing getting-started.md.

src/en/getting-started.md
+will process all of the events that occur. These instructions will walk you
+through using the hosted Juju as a Service (JAAS) controller and requires you
+to have public cloud credentials ready. If you'd prefer to test it out
+locally, we've got a tutorial on setting up a [LXD based controller over
@degville

degville May 9, 2017

Collaborator

'over here' sounds a little too casual to me, although I appreciate you're trying to be less formal. We'd normally write something more like see our _Getting started with Juju and LXD_ guide further details.

@mitechie

mitechie May 9, 2017

Owner

reworded

src/en/getting-started.md
-```no-highlight
-Use --refresh flag with this command to see the latest information.
+When you have selected a charm or bundle (hint: to see how easy JAAS makes
+complex deployments, try the Canonical Kubernetes bundle!) it can be added
@degville

degville May 9, 2017

Collaborator

I think we should add a link to https://jujucharms.com/canonical-kubernetes/

@mitechie

mitechie May 9, 2017

Owner

+1 added

src/en/getting-started.md
-Use --refresh flag with this command to see the latest information.
+When you have selected a charm or bundle (hint: to see how easy JAAS makes
+complex deployments, try the Canonical Kubernetes bundle!) it can be added
+to your model by pressing the 'Add to model' button...
@degville

degville May 9, 2017

Collaborator

It may be more consistent to replace the ellipsis with a colon.

@mitechie

mitechie May 9, 2017

Owner

reworded

src/en/getting-started.md
+## Use the command line
+
+Juju can also be used from the command line. Models you've created in JAAS are
+also able to be operated against via the CLI and vice versa. In order to use
@degville

degville May 9, 2017

Collaborator

this sounds clunky to me. How about, Models created with JAAS can also be operated on from the CLI, and vice versa - models created on the CLI can be modified by the GUI.

@mitechie

mitechie May 9, 2017

Owner

reworded

src/en/getting-started.md
+Click on the sections below for the relevant instructions or visit the
+[install instructions][install] for a thorough run down of your options.
+
+To most quickly get started pick your OS from below.
@degville

degville May 9, 2017

Collaborator

I'd suggest Get started quickly by picking your OS from below:

@mitechie

mitechie May 9, 2017

Owner

ty, updated

src/en/getting-started.md
+
+ sudo snap install juju --classic
+
+ You can check which version of Juju you have installed with
@degville

degville May 9, 2017

Collaborator

with: (colon)

@mitechie

mitechie May 9, 2017

Owner

ty

src/en/getting-started.md
+
+## Register or login to JAAS
+
+To connect to JAAS from the command line you'll need to login. Enter the following command:
@degville

degville May 9, 2017

Collaborator

on the command line, login could be ambiguous. How about authenticate the CLI against JAAS with the following command:

@mitechie

mitechie May 9, 2017

Owner

reworded

src/en/getting-started.md
+After successful authentication, you will be asked to enter a descriptive name
+for the JAAS controller (we suggest JAAS). Now you can operate your models or
+applications in JAAS from the command line. You can see a list of all of your
+controllers using the cli command:
@degville

degville May 9, 2017

Collaborator

Uppercase CLI was used earlier (we normally write command line).

@mitechie

mitechie May 9, 2017

Owner

updated cli to command line throughout

src/en/getting-started.md
+hours of looking up config options or wrestling with install scripts!
+
+To discover more about what Juju can do for you, we suggest some of the
+following pages of documentation
@degville

degville May 9, 2017

Collaborator

documentation: (colon)

@mitechie

mitechie May 9, 2017

Owner

ty

src/en/jaas-cli.md
sudo snap install juju --classic
- You can check which version of Juju you have installed with
+ You can check which version of Juju you have installed with
@degville

degville May 9, 2017

Collaborator

with: (colon)

@mitechie

mitechie May 9, 2017

Owner

ty

@mitechie
Owner

mitechie commented May 9, 2017

Pushed an update addressing the changes requested by @degville
@evilnick

evilnick requested changes May 9, 2017
View changes

some final minor tweaks!

src/en/getting-started.md
-the command line, you will first need to install the Juju client software on
-your machine.
+Juju can also be used from the command line. Models you've created with the
+JAAS website can also able to be operated via the normal Juju command line. In
@evilnick

evilnick May 9, 2017

Member

I think if you delete 'able to' here, we're golden

@mitechie

mitechie May 9, 2017

Owner

agree, remoed

src/en/getting-started.md
@@ -251,7 +253,8 @@ output.
After successful authentication, you will be asked to enter a descriptive name
for the JAAS controller (we suggest JAAS). Now you can operate your models or
applications in JAAS from the command line. You can see a list of all of your
-controllers using the cli command:
+controllers using the command line command:
@evilnick

evilnick May 9, 2017

Member

I would just put 'command:' or 'command line:'

@evilnick

evilnick May 9, 2017

Member

actually, I prefer just 'command:'

@mitechie

mitechie May 9, 2017

Owner

ty for the catch.

@mitechie
Owner

mitechie commented May 9, 2017

Updated, ty for the reviews. Please let me know if there's anything else that catches your eyes.
@evilnick
Member

evilnick commented May 10, 2017

This looks okay now, but we will have to sort out the navigation due to pages removed/moved. Do you want to do that here?
@mitechie
Owner

mitechie commented May 10, 2017

Ah, that's a good point. I'd not looked at the nav setup. Might as well do it here to test it out and make sure it all works with the changes/file moves here.

I'll update shortly.
@evilnick
Member

evilnick commented May 10, 2017

Cool. You'll find the 'navigation.tpl' in the src folder. It's just html so reasonably straightforward
@mitechie
Owner

mitechie commented May 10, 2017

Is the nav.txt in the tools still used?

mitechie added some commits May 10, 2017

@mitechie
Merge branch 'master' of github.com:juju/docs
9886587
@mitechie
Add the start of the install doc page
47ca477
@mitechie
Clean up the getting-started and the install ref. 
- I tried to remove the old reference-releases
- Updated the content on the reference-install
- Worked to clean up references to the releases page.
- The general getting-started seems like dupe content only used from the jaas
page.

Some other gardening.
fde28c4
@mitechie
Updates on the tut-lxd per review
91302bf
@mitechie
Updates per review
576a3f9
@mitechie
Update per review
074d3bd
@mitechie
Update per review
4b3b9d4
@mitechie
Update nav and correct links 
- Updated the nav with the new getting started setup
- Renamed the Get started with "Quick Guides" to more accurately name them.
- Moved the Juju 2/2.1 to the references section so that it's not top billing.
2.0's been out for a while and the what's new is more of a releases thing.
- Fixed a couple of links that still went to references-releases.
128f75c
@mitechie
Fix merge conflicts
c322caa
@mitechie
Owner

mitechie commented May 10, 2017

I've updated the nav, corrected merge conflicts with the branch from upstream, and fixed a couple of links.
@mitechie
Owner

mitechie commented May 10, 2017

@evilnick I'm hitting https://www.bountysource.com/issues/36261101-python-3-syntaxerror-from-long-literal-0x950412del-in-po-msgfmt-py trying to get the linkchecker installed and test out the links. Can you run it and let me know what needs to be corrected? I'm assume I've got to have missed something in the changes.
@evilnick

evilnick requested changes May 10, 2017
View changes

Some notes on nav renames

src/navigation.tpl
<!-- SECTION -->
- <li class="section"><h4 class="header toggle-target">Get Started</h4>
+ <li class="section"><h4 class="header toggle-target">Quick Guides</h4>
@evilnick

evilnick May 10, 2017

Member

Why change the name of the get started section? I realise that this now incorporates more tutorial elements, but I think changing both the name of the section and the name of the link to the getting started page (which is now First Use!) means that we have nothing called 'Getting/Get started'. Actually, I would be more in favour of accepting this change, but changing the link for get started back to 'Get started'

@mitechie

mitechie May 10, 2017

Owner

I guess I've been in too much "getting started" all over the place and as we're starting to refer to things as tutorials or guides I thought it might be a good update to reduce using "getting" so much any more. I'm +1 on moving the First use to the new "Get started". I almost did that in here.

@evilnick

evilnick May 10, 2017

Member

Yes, it is a pain, but it is also a common signpost, so I think it is useful to keep somewhere!

src/navigation.tpl
- </li>
- <li><a href="getting-started-jaas.html">Juju as a Service (JAAS)</a></li>
+ <li class="section"><a class="header" href="getting-started.html">First use!</a></li>
+ <li><a href="tut-lxd.html">Local Juju with LXD cloud</a></li>
@evilnick

evilnick May 10, 2017

Member

I think we can come up with a better name for this. For one thing, LXD isn't the benefit, so it is rather irrelevant to messaging (LXD is how we deliver what they want).
Alternative suggestions - Juju on a no-cost, local cloud

@mitechie

mitechie May 10, 2017

Owner

I think that it's worth keeping the lxd branding going. I worry about it being too generic and folks heading here that don't have or can't use LXD on their systems.

@evilnick

evilnick May 10, 2017

Member

hmmm. Yes, that is an issue. I don't think its worth holding up the rest of the updates for though, but I think we should work on a better name

src/navigation.tpl
@@ -195,14 +189,16 @@
<!-- SECTION -->
<li class="section"><h4 class="header toggle-target">Reference</h4>
<ul>
+ <li><a href="reference-install.html">Install Juju</a></li>
+ <li><a href="introducing-2.html">Introducing Juju 2.0!</a></li>
+ <li><a href="whats-new.html">What's new in 2.1</a></li>
@evilnick

evilnick May 10, 2017

Member

I'm not sure why we have moved this down to the reference section. It has very little visibility down here. I think the Juju 2.0 stuff is okay down here, but I feel there ought to be a 'what's new' link at the top

@mitechie

mitechie May 10, 2017

Owner

I'm +1 when we do the what's new with 2.2 at the top? I guess I feel like there's a time window here and 2.1 is old enough that it pushes more important stuff down.

@evilnick
Member

evilnick commented May 10, 2017 •
Edited 1 time

@mitechie yeah, the linkchecker is a pain - such a useful tool, but pretty much abandoned now. It doesn't work with Python3 at all. Are you trying to get it working on a Mac? It works on xenial with 2.7 and 3 installed.

I think there are some references to jaas-getting-started, which need to be updated, but I will try it out here
@evilnick
Member

evilnick commented May 10, 2017

@mitechie yup, the following help pages still reference getting-started-jaas:

help-azure
help-google
help-aws
@mitechie
Owner

mitechie commented May 10, 2017

Updated the name of the nav link for Get started and updated the broken link pages notes. Thanks for checking those.
@evilnick

evilnick approved these changes May 10, 2017
View changes

🍰

src/navigation.tpl
- </li>
- <li><a href="getting-started-jaas.html">Juju as a Service (JAAS)</a></li>
+ <li class="section"><a class="header" href="getting-started.html">First use!</a></li>
+ <li><a href="tut-lxd.html">Local Juju with LXD cloud</a></li>
@evilnick

evilnick May 10, 2017

Member

I think we can come up with a better name for this. For one thing, LXD isn't the benefit, so it is rather irrelevant to messaging (LXD is how we deliver what they want).
Alternative suggestions - Juju on a no-cost, local cloud

@mitechie

mitechie May 10, 2017

Owner

I think that it's worth keeping the lxd branding going. I worry about it being too generic and folks heading here that don't have or can't use LXD on their systems.

@evilnick

evilnick May 10, 2017

Member

hmmm. Yes, that is an issue. I don't think its worth holding up the rest of the updates for though, but I think we should work on a better name

@evilnick
Member

evilnick commented May 10, 2017

Ok, I'll merge this now. We will have to backport all the changes to get it into 2.1,
I will take a stab at that tomorrow

@evilnick evilnick changed the title from (WIP) Rework the getting-started sections of the docs. to Rework the getting-started sections of the docs. May 10, 2017

@evilnick evilnick merged commit e9f0e2e into juju:master May 10, 2017

@mitechie
Owner

mitechie commented May 10, 2017

Thank you for working with me on the updates. Appreciate all the sanity checking and time spent.
@evilnick
Member

evilnick commented May 10, 2017

NP, thanks for all the work you did!

@evilnick evilnick referenced this pull request May 12, 2017

Closed

very confusing that the "getting started pages" links you to a "getting started page" #1703

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment