Doc for newbies

[ptoche]

Suggestion to improve the documentation for newbies:

I have never used Julia/Juno, etc. but I'm keen to get started.

From the Juno website welcome page (http://junolab.org/), one gathers the following info:

• Juno is an IDE aka an environment for the Julia language .
• Juno is built on Atom, which is a powerful editor

In the setup.md (https://github.com/JunoLab/uber-juno/blob/master/setup.md), one learns that to Get Juno one must Get Julia and Get Atom. Under Get Atom one is instructed to install the uber-juno package. So is that all there is to it? Does the following hold?

  Juno =  Atom + uber-juno + Julia

If so, perhaps a sentence along the lines of "Juno is a package named uber-juno that enables the powerful text editor Atom to communicate with the Julia language" could be added to the top of the setup.md. And if there is more to it, a sentence to clarify what else Juno is about. Thanks.

[pfitzseb]

Well, Juno is an IDE, which means it provides tools to efficiently code in some language.

In this case, it consists of a couple of quite a few parts (multiple Julia and Atom packages), which the uber-juno package installs. The basic editor functionality (and the package framwork and autocompletions and so on) is provided by Atom; whether you count Julia as part of the IDE or not is up to you (I'd say no though).

All of that seems like an implementation detail to me though, something that shouldn't necessarily be exposed to users. In the case that someone doesn't want all of what Juno provides (like default settings), we could maybe have manual installation instructions for all related packages. Those would then also make the internal structure and stuff clearer...

That said, I guess it'd be clearer to structure the install instructions a bit differently -- maybe something like

---

Getting Juno

Getting Juno takes a couple of simple steps and just a few minutes. Follow this and you'll be running Julia code in no time!

Getting Julia

First, download Julia (command line version) for your platform from the downloads page.

Then:

On Windows

1. Run the downloaded installer, using the default settings.

On OS X

1. Double-click the downloaded disk image to load it.
2. Drag the Julia-0.X.Y app onto the Applications folder shortcut.

On Linux

1. Unzip the downloaded folder and place it in your home directory.

Getting Atom

Download, install and open Atom. If you have it already, make sure it's up to date (version 1.7+).

Installing Juno

In Atom, go to Settings (Ctrl ,, or Cmd , on OS X) and go to the "Install" panel.

Type uber-juno into the search box and hit enter. Click the install button on the package of the same name.

Atom will then set up Juno for you, installing the required Atom and Julia packages. Once the setup is done you're good to go!

---

would be better?

By the way, thanks for taking the time and providing feedback!

[ptoche]

Hi pfitzseb, thanks for your reply. Yes, this new layout is clearer.

The confusion is about how the different pieces fit it, how Juno, Atom and uber-juno fit in.

At the top of the setup.md, right below Getting Juno, I would find it useful to have a sentence explaining why I need both Atom and uber-juno and the relation between Juno and uber-juno (Is Juno a pretty name for uber-juno? ).

To add to the confusion, a short while back I had installed a Juno bundle. Not sure how I'd got to that. I have a feeling I should not have both the Juno bundle and Atom+uber-juno, right? Useful would also to have a sentence explaining whether this Juno bundle is obsolete/experimental. If someone has it installed, should they remove it first?

A great deal of my confusion comes from having installed this Juno bundle a few weeks back... (it goes under the name of juno-mac-x64.dmg for OSX).

[MikeInnes]

@ptoche I think what we can try here is if we go over things in detail, and once it makes sense to you, you can tell us how to explain it back to others ;)

So Juno is composed of a lot of different parts:

• Atom, a text editor (like Sublime Text or Notepad or whatever)
• The Julia Language (the interpreter/compiler)
• julia-client, an Atom package (and another package called ink which is effectively a dependency)
• Atom.jl, a Julia package

When all of these things come together you get Juno. There isn't really one thing you can point to and say "that's juno", unfortunately.

There's also a package called uber-juno which is pretty much just an install script. You install it in atom, it grabs the atom packages, it sets up some config, it launches Julia and installs the Julia packages. But it's purely a convenience, you could do this all yourself and uber-juno provides zero functionality after that point. (Perhaps renaming it to install-juno would help.)

We also had a bundle at one point that included all of these things in a single installer, which made the "that's juno" problem much easier. But it had issues – most notably more difficult auto-updates – so we discontinued it a few months back. It will have no bearing on the new install so keep it or don't.

Does that clarify things? I'd definitely like to reduce setup confusion as much as possible, although ideally we can "abstract over" some of this in an intuitive way rather than needing people to understand in detail. It's also really crucial that our setup is simple-looking – i.e. not a wall of text – but we can always link from setup.md to other articles if needed.

[ptoche]

@MikeInnes, this is extremely clear. How about a sentence like "If you install Julia, Atom and the uber-juno package, you will have a Juno setup. If you'd like to know more about how the different pieces fit in, about dependencies, about ongoing developments, read this" where the "this" would be a link to the explanation you just wrote above!

It would probably be too much to have it all detailed in the setup.md, but a link to your explanation for the confused and/or curious user would be a great addition to the doc.

Thanks to both of you for the feedback.

Edit: This sentence I have since come across, Juno is implemented as a large collection of independent modules and plugins, might be worth having too.

[ptoche]

Btw, once the confusion moment has passed, the experience is quite smooth!

I was able to change a key binding by just going into Preferences --> Keybindings and following the instructions there. Very simple. Very clear doc for this particular feature.

'atom-workspace':
  'cmd-shift-c': 'julia-client:clear-console'

The default cmd-j cmd-c seemed like an unlikely shortcut for something as standard as clearing the console.

[ChrisRackauckas]

I'll make sure to mention this in JunoLab/Juno.jl#6

[Jinnd319]

I'm not seeing an installer for juno anywhere on my computer. How do I get juno? I'm on windows. I already have julia. I installed it from the linked page.

[pfitzseb]

Have a look at the docs.