Documentation: Update "Installation" guide with clearer guidance on build tools and CDNs

[donmccurdy]

I think @drcmda is correct in the comment thread here — our current installation guide doesn't get users to a simple working setup as directly as it could. We've got sections on Microsoft IIS and Ruby servers, but nothing on a (much easier) Vite setup that can handle imports for you, and the instructions on CDNs and import maps could be simplified too.

That's partly on me — the last rewrite, in 2020, focused on introducing ES Modules but didn't give a decent story for build tools. I think we should also be consistent about showing imports that refer to "three" rather than a direct URL pointing to a CDN, and leave resolution to import maps or the build tool.

To improve things, I'm proposing a couple changes:

1. The Installation guide is now the first link under Getting started, and explains basic project structure that will be used in the Creating a scene section afterward.
2. The Installation guide offers two pathways: (1) Installing with a build tool, and (2) Installing from a CDN. I've tried to make both as easy as possible, but necessarily some details are not covered, like alternate build tools, or using 100% local files instead of a CDN.
3. The How to run things locally guide is removed — it's covered under Installation now — and the Creating a scene guide is updated to fit with everything else.

This should also fit well with what Bruno describes in the three.js journey / Local Server video.

Preview:

• Documentation / Installation

[mrdoob]

Option 2: Installing from a CDN

How about Importing from a CDN instead?

I think the CDN approach is more common for people using codepen & co.
These people don't even need npm or a server, no?

[donmccurdy]

How about Importing from a CDN instead?

Done!

These people don't even need npm or a server, no?

I think that's correct, it's OK to the local server in the guide here though right? As opposed to pointing people to Codepen etc.?

[marcofugaro]

Cool! This looks good to me 👍

[hermannji]

On the installation catalogue. The first 2 paragraphs.


#################

Installation

Most web developers install JavaScript libraries like three.js from the npm package registry, then develop their project using build tools like Vite or Webpack. Because three.js is also popular with many communities that may not be as familiar with these tools, this guide also describes a simplified "static" installation using a CDN instead of a build tool.
#################

I think overwhelmingly, when users enter the installation catalogue, their feeling is.
"How do I install this thing".

And I would address that by simply enlisting the ways in which it can be installed. So I would replace the installation paragraph with the following.

Threejs can be installed in the following ways:

1. Npm (popular)
2. CDN

The links can then be later placed underneath the npm Option.

#################
Quickstart

If you already know how to set up a project and install npm dependencies, you can skip the rest of this Installation guide and install three.js with the line below. Otherwise, continue to Project structure section.

npm install --save three
#################

If the user already knows how to install Threejs, I don't think they will enter the installation catalogue.
Also the "Otherwise, con.." part is redundant as its simply referring the the next paragraph. Which is what people naturally read anyways.
So we can skip this text. It's redundant.

The installation line can then be moved to be the first thing under the npm category.




Then there comes the project structure, which is legit. But maybe compartmentalize it somehow more. It's like a unit. On it's own in there.

Then there comes:

Option 1: Installing with a build tool

But that's just the Npm option so I would replace it with:

1: Npm

[donmccurdy]

Thanks @hermannji! I've addressed most of that I think.

But maybe compartmentalize [project structure] somehow more. It's like a unit. On it's own in there.

I didn't understand what you mean here, sorry. I'm happy with this section as it is, but could be open to more specific changes.

[hermannji]

Thanks @hermannji! I've addressed most of that I think.

But maybe compartmentalize [project structure] somehow more. It's like a unit. On it's own in there.

I didn't understand what you mean here, sorry. I'm happy with this section as it is, but could be open to more specific changes.

Regarding paragraph Project Structure

The Name
The thing is, that this is the structure the user will start with.
But then users build their own structure on top of it.
So in most cases, this will not be the Project Structure in the eyes of the users.
It will just be the initial project structure.
I would call this Initial Project Structure, which becomes "Hello World".
Everybody relates to Hello World.

The Location
Project Structure is currently under installation.
But it's a bit off having it there.
Project Structure is related to installation, yes, but it's not actually installation.
So I would move paragraph "Project Structure", to it's own category,
and call it "Hello World" and place it first under "Getting Started".

Redundant Newlines
There are a few extra newlines in the structure display,
after index.html and a couple more further down.
Might just be a redundant <br>.

Index Title
In Project Structure, file index.html, the title node.
I would just give it the text "Hello World".
Apps are usually just for phones.
People can have different thoughts on the matter but no need to complicate the matter with it.

One Click Hello World
I would also add a link under Project Structure,
which people could click to download the "Hello World" folder ready-made.
And have it named perhaps, "3js_Hello_World".

[donmccurdy]

Thanks @hermannji! I appreciate your review. On the remaining points, I think that I prefer how the PR is written now. You are certainly welcome to propose improvements in a new PR if you'd like though, we can always improve this more.

[hermannji]

Thanks @hermannji! I appreciate your review. On the remaining points, I think that I prefer how the PR is written now. You are certainly welcome to propose improvements in a new PR if you'd like though, we can always improve this more.

What does PR stand for?
How do I do that?

[donmccurdy]

PR is short for "pull request", which is just to say that after this change is merged, you can propose any changes to the file. GitHub has a helpful guide on this.