Guide: Installing node about docs

[Qard]

Demonstrating different approaches to installing would probably be helpful. ie: installing via nvm, nave or n, installing via homebrew, installing via node source apt repos.

Walking through some basic node command-line usage would be good too. Like node app.js to start an app, node to start the repl.

[bnb]

I would be willing to write a version or section on how to install Node with Windows. Is this for Node 0.12 or the-software-formerly-known-as-io.js 2.2.1?

[danielkhan]

Ok - then we should maybe split this up anyways.

• Different OS (I could do OSX, and Linux, great if another person does windows as I need a VM for that)
  • different installers by system
  • command line commands to verify it is working

For the node app.js part and the repl part maybe a separate 'First Steps' document would be an option? This could be crosslinked with the install docs.

[Qard]

Have a look at how rust does getting started docs. That seems like a good starting point. Their docs are very good. :)

[danielkhan]

Ok should we structure it like rusts docs? Anyone against that?

[chrisdickinson]

Following rusts' example would not be a bad idea. You may also look at how Django structures theirs. I might add that it'd be good to:

1. explicitly pick an audience you're targeting (folks new to programming, folks new to node, etc) and write to that,
2. Include "did it work" steps to verify installation,
3. note that there are many ways to skin this cat, and add some stub articles for homebrew, installing from source, debian packages, windows, and n/nvm/nave. Then we can link to em.
4. Could you create the guides/ dir and put this document in there?

On Jun 18, 2015, at 2:18 PM, Stephen Belanger [email protected] wrote:

Have a look at how rust does getting started docs. That seems like a good starting point. Their docs are very good. :)

—
Reply to this email directly or view it on GitHub.

[danielkhan]

I'll do.

[bnb]

Again, I'd like to ask about the timeliness of this - should we wait until there is a solid foundation of Node, with an actual release after the merger? Right now, we're in a sort of limbo where the newest version is io.js, but Node is the namespace which we will be speaking under. If we were to direct them to Node 0.12, that'd be a bit like throwing them under the bus. I see it as having high probability to confuse newcomers.

[bengl]

@bnb I'm not entirely sure it matters. Installation is (hopefully (IIRC)) relatively consistent across versions. Shouldn't we be able to just point them at https://nodejs.org/download ?

EDIT: Put another way: Is recommending a particular version a requirement for a complete installation guide?

[bnb]

@bengl I think it should be aimed at the newest version - the newest version of io.js isn't represented at all in the link you provided. The LTS WG would be the one to talk to about maintaining install instructions for previous versions. Essentially, right now it's giving people a suggestive UI for an old version of what is now called Node, whose support is up in the air at the moment - up to whatever the LTS WG decides. As I said, it can be confusing - being given UI that makes version 0.12 seem current when you've heard the newest version is 2.x.x is a big problem.

Edit: /cc @nodejs/LTS

[Qard]

I would say point them at latest for now. The whole point of coordinating this docs effort through github is that updates are trivial. We can revisit the install docs later when names change or "stable" is more clearly defined.

[danielkhan]

There is a link to io.js - is the location it points to deprecated?

I also think that we should start to move, knowing that we are dealing with moving targets and adopt things when they become clearer. Maybe my writeup isn't usable at all but if we don't start writing and reasoning about the outcome we will have a hard time when a new, stable release is finally there. I'm quite sure that this won't be a one shot but a process until we find a common structure and tone for every kind of material we want to provide, don't you think so?

[bnb]

The difference I was trying to convey was that there's a table with images, interactivity, and types/versions of downloads for the current "Node" release, while the link to io.js is hidden in a paragraph. I just think that the docs should be more clear about the fact that io.js' current state is what Node will be adopting. Telling people to install something that is essentially outdated is not good practice.

[danielkhan]

O.K. but then this page should be changed. The docs should be agnostic, I think.

[bnb]

What would the structure for the docs being agnostic look like?

[danielkhan]

I have to add one thing first. IMHO currently Node.js 0.12 is the current stable version. Although it might be somehow outdated compared to the current io.js, moving the userbase to the new converged version will take quite some time. Especially for enterprises.
I am not fond of selling io.js within the docs. I think this would be greatly confusing.
The way the download page explains things is from my perspective all there is to say about this topic for now and reflects the current state of affairs.

To tell users which version is currently recommended to install has huge impact and is out of scope of this WG, I think. So I don't want to get into this topic too much if possible.

The structure for the agnostic doc would be:
Show the different ways to install node.js on different platforms. From Linux to Windows, from nvm to apt-get. The download link points to https://nodejs.org/download as this is the current Node.js version.
Users can choose which flavor they like. The docs just show how to install it.
This page can change at any time without needing the docs to be adopted.

[chrisdickinson]

Who is this document for?

If it's for newbies, we should probably point them at the version that is most likely to universally work for them. Explaining the difference between the versions comes after that, perhaps as a separate document.

On Jun 18, 2015, at 8:11 PM, Daniel Khan [email protected] wrote:

I have to add one thing first. IMHO currently Node.js 0.12 is the current stable version. Although it might be somehow outdated compared to the current io.js moving the userbase to the new converged userbase will take quite some time. Especially for enterprises.
I am not fond of selling io.js within the docs. I think this would be greatly confusing.
The way the download page explains things is from my perspective all there is to say about this topic for now and reflects the current state of affairs.

To tell users which version is currently recommended to install has huge impact and is out of scope of this WG, I think. So I don't want to get into this topic too much if possible.

The structure for the agnostic doc would be:
Show the different ways to install node.js on different platforms. From Linux to Windows, from nvm to apt-get. The download link points to https://nodejs.org/download as this is the current Node.js version.
Users can choose which flavor they like. The docs just show how to install it.
This page can change at any time without needing the docs to be adopted.

—
Reply to this email directly or view it on GitHub.

[bnb]

I'd like to know what some of the core io.js developers think. (// cc @mikeal, @rvagg, @bnoordhuis, @indutny, @piscisaureus, @trevnorris; your views on this will help me understand the official position better.)

@danielkhan I think we have differing opinions on the way "current version" should be handled.

I guess my question is: there are inherent differences between the install pattern for io.js and Node's 0.12.x branch. One of these is the download link - when you're telling someone how to download something, you need to instruct them to go to a specific link for their platform. As I understand it, you'd be encouraging the 0.12 branch. I don't really see that as agnostic.

Apologies if I'm over-thinking this, or am coming off as rude - that's not my intention. I see that we have differences in the way we think this should be done, and I'm trying to solve the issue in the best way I can both for the sake of the documentation's readers and us as its writers. I don't mean to force my way of thinking onto anyone, I just want to come to a conclusion that we can all be happy with.

[danielkhan]

I just wanted to get the ball rolling. If it needs to roll into this discussion before we can proceed that's fine for me.

I still need to understand your point and use case, though because

• after the merge it will be neither the current 0.12 Node version nor the current io.js - it will be a new, merged version
• the brand name will be Node.js - so why confuse people now with io.js?
• if people are looking for docs on Node.js they want to install Node.js

With agnostic I mean that I will link to the download page that reflects my point of view very well.
I don't mean that I would want to go into io.js inside the docs because this is simply not the brand I am writing the docs for.

[bnb]

Let me try to address your points:

• I read in one of the io.js repos that the new Node version will adopt the current io.js version number. So, if there's not another release by the time they merge, the Node version will be 2.2.1.
• The brand name is Node.js - however, given the above, the code base will be mostly io.js' updated version, with the new features of Node 0.12 patched in. This is one of the challenges that we face with writing this documentation, and can only be solved by explanation. As long as io.js' current release is given first-class citizenship in the docs, I'm fine with it being explained in addition to the Node 0.12 explanation. We're all in a sort of limbo right now, and explaining this is one of our challenges.
• Again, this is where our ideas of what Node.js is differ. io.js is Node.js - we're just in a state where there are two versions of Node.js, and the differences are being sorted out by the TSC wizards.

I'd say that the branding right now is irrelevant. I agree that you're not writing for io.js - right now, that name is just an artifact of what was a fork of Node.js, whose content is being pulled back into Node.js under the Node.js branding. Essentially, if you write against Node 0.12, you're writing something that is guaranteed to be outdated within a very short time span - why not write for the future that is 100% certain?

[danielkhan]

I am aware of the ongoing process and I am also quite aware of its implications especially as my company invested quite some time and effort to support the current Node.js development line in its products. I also think that it will take at least one year until enterprises can switch to any new version of Node.js.

Said that I really doubt that the installation - and this is what this issue is about - will work differently than now and I really don't think that version numbering is on the slate for this discussion either.

The usual way is to have static links to latest or stable and one to unstable or development regardless of the versioning. The docs should never contain a version number.

[bnb]

Okay, I can get on board with that. Would you agree to having a link to another docs page that explains the situation with Node + io.js merging to make the Node Foundation? Could this page explain the version variance, or link to yet another docs page that does?

[danielkhan]

Perfect. Sure I am agreeing with this because not explaining the whole io.js thing could also confuse users.

Any other thoughts? Anyone?

[mhdawson]

In respect to @bnb 's last comment I'm thinking that @jasnell who is helping to drive the convergence work should be involved at least as a reviewer for the docs page that explains the the situation with Node + io.js merging to make the Node Foundation

[jasnell]

I'll definitely review. Just may take an extra day or two while I recover
from vacation ;).
On Jun 19, 2015 7:11 AM, "Michael Dawson" [email protected] wrote:

In respect to @bnb https://github.com/bnb 's last comment I'm thinking
that @jasnell https://github.com/jasnell who is helping to drive the
convergence work should be involved at least as a reviewer for the docs
page that explains the the situation with Node + io.js merging to make the
Node Foundation

—
Reply to this email directly or view it on GitHub
#7 (comment).

[sam-github]

@bnb you might find this useful, its how we recommend people install node on windows: http://docs.strongloop.com/display/SL/Installing+Node+and+StrongLoop+on+Windows

[chrisdickinson]

@bnb:

I'd like to know what some of the core io.js developers think. (// cc @mikeal, @rvagg, @bnoordhuis, @indutny, @piscisaureus, @trevnorris; your views on this will help me understand the official position better.)

You can reach all of us with @nodejs/tsc. My two cents: I'd prefer that we point initial installs at v0.10 until the release channel discussion reaches a definite conclusion. We can easily change the text around this in the future – for the moment, better to point at something rather than at nothing.

@danielkhan It occurred to me that I have an idea of who this document should address, but it might not be the same folks you have in mind. Who are you planning on addressing?

Folks talking about adding an article explaining the convergence, the versioning system, or the relationship between io.js and Node: open new issues for these articles! Include the audience you're trying to address, and what message or idea you want to convey in the issue text.

[danielkhan]

My target group would be people that want to install Node.js - as simple and maybe naive as that. That might be newbies but also people that look up the current best practices to install it.
What is the audience you had in mind?

[misterdjules]

@chrisdickinson Why would v0.10.x be the recommended version of Node.js to install? That is probably related to my question here: nodejs/node#1997 (comment).

[chrisdickinson]

@danielkhan:

My target group would be people that want to install Node.js - as simple and maybe naive as that. That might be newbies but also people that look up the current best practices to install it.

It might be best to separate newbies out from an in-depth installation guide. There are a lot of (completely valid) ways to get a working copy of node and npm onto your system — but newbies just need to know one way, and to be able to rely on that way working.

We definitely need both guides – "how to install" for newbies, and an exhaustive "how to install" for experienced devs.

@misterdjules:

Why would v0.10.x be the recommended version of Node.js to install? That is probably related to my question here: nodejs/node#1997 (comment).

My rationale for wanting to point newbies at v0.10 is that I want to make sure we're pointing them at a version that is exceedingly unlikely to do anything unexpected on them, and is imminently google-able when something does explode.

If this guide is meant to be more comprehensive – targeted at experienced programmers – then the above concern doesn't apply.

[danielkhan]

@chrisdickinson

It might be best to separate newbies out from an in-depth installation guide. There are a lot of
(completely valid) ways to get a working copy of node and npm onto your system — but newbies just
need to know one way, and to be able to rely on that way working.

I am currently trying to get this done within one document - let's see how it works. We can split it up or dump it afterwards.

[misterdjules]

@chrisdickinson v0.12.x is the current stable version. I believe it is unlikely to do anything unexpected on new users in terms of installation. Regarding the installation process, I believe what applies to v0.10.x also applies to v0.12.x, so I would think that most documentation and answers online about v0.10.x apply to v0.12.x.

Also, npm shipped with v0.12.x is current, whereas npm shipped with v0.10.x is very old. I can see that as a major source of problems for new users.

Do you have specific, concrete concerns about v0.12.x and its usage by new users?

My main concern here is that the work done by maintainers of the current stable version of Node.js is focused on v0.12.x. Directing users at v0.10.x would send a confusing message and would not help users or maintainers, as users would use a version that is not considered by maintainers to be the primary focus.

[chrisdickinson]

@misterdjules Let's wait to see what @danielkhan comes up with:

• I don't envision it being too terribly hard to switch the version we're talking about installing.
• I don't want to block this documentation on an argument that should happen elsewhere, especially if it's going to be easy to change here.
• It's probably too soon to worry about directing users to the wrong version. This repo is not linked up to any site and exposes a single, mostly-empty src directory at top level, with no README.

Ultimately we're going to recommend whatever the LTS group / release discussion says we should recommend.

[misterdjules]

@chrisdickinson I don't mean to block anything, I want to avoid the situation where a lot of new users read some documentation that mentions v0.10.x as the version to install by default, or some kind of LTS, when as you said this should be recommended by the LTS group. It seems we're on the same page about this so it's all good 👍

[bnb]

👍 as well. For me, at least, I (stupidly) adopted the attitude that we're shipping to production right away, which I now see was never the case. Apologies for adding to the blockage.

[danielkhan]

Can someone elaborate on what will happen to wiki pages like https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager - at the beginning there is now a note that the wiki page will undergo a full update. I am currently writing the linux part for our docs - how does the wiki relate to us at all and can we incorporate parts?

[rvagg]

You can copy as much of the readme @ https://github.com/nodesource/distributions as you want which contains info on how to install the various versions on Linux, it's quite complicated now with all of the versions available but that's just the way it is.

We still don't have full support across Linux distros for 0.12 and io.js for build-chain and complexity reasons but I expect that to be sorted out soon.

[danielkhan]

I failed to do that.