Refactor Install page before moving a copy to webdev #727

chalin · 2018-03-30T20:22:22Z

Contributes to #657.

Staged, see:

Install page is now like the Platoforms, but it directs the user to installation instructions appropriate for the chosen platform:

The Web and VM installation instructions now make use of @filiph's compact OS-tabbed instructions (slightly enhanced with a bit of extra information):

cc @JekCharlsonYu @anders-sandholm

filiph

LGTM!

kwalrath

I like the general direction, but there are a bunch of details we need to work out.

kwalrath · 2018-03-30T20:49:14Z

src/install.md

+
+Choose your platform.
+
+{:.card-grid}


There's a lot of white space surrounding these cards, which means that usually I see only two platforms on the first line, even when my window is pretty wide. Also... Why are these indented?

I believe that this is the same layout and spacing as the platforms page, but I'll double check.

I confirm that we're using the same card-grid and card styles in other pages, and that the cards have the same width, etc. E.g., see the cards on these pages:

https://www.dartlang.org/guides/language

https://www.dartlang.org/guides/libraries

https://www.dartlang.org/guides/platforms

I don't suggest that we start making one-off changes. Later we might want to consider a site-wide revision of styling.

WDYT?

Given that the "platform" cards are mostly white, I suppose that I could make those narrower (on both the platform and install pages). Let me try something ... .

It looks better, thanks.

kwalrath · 2018-03-30T20:49:35Z

src/install.md

+
+  ### [Flutter][Flutter install]
+
+  Flutter SDK install.


Let's say: Get the Flutter SDK.

kwalrath · 2018-03-30T20:50:28Z

src/install.md

+
+  ### [Web][Web install]
+
+  Dart for web install.


Maybe: Get the Dart SDK plus web-specific tools.

kwalrath · 2018-03-30T20:51:09Z

src/install.md

+
+  ### [Dart VM][Dart install]
+
+  Dart SDK install.


-> Get the Dart SDK.

kwalrath · 2018-03-30T21:13:48Z

src/tools/sdk/_linux.md

@@ -0,0 +1,41 @@
+#### Install using apt-get


We need some intro text before this, or else it isn't clear that you have a choice between apt-get, debian, and compiling from source. (It looks like the text is there in https://www.dartlang.org/install/linux, so it should be easy to grab. I guess formatting is the only issue. We lose a lot of navigation when we give up the page and its TOC.)

kwalrath · 2018-03-30T21:16:09Z

src/tools/sdk/_windows.md

@@ -0,0 +1,33 @@
+#### Install using a setup wizard
+{: style="margin-top: 0"}
+


As for the Linux page, we need an overview here.

kwalrath · 2018-03-30T21:16:54Z

src/tools/sdk/_windows.md

@@ -0,0 +1,33 @@
+#### Install using a setup wizard


The style of these 4th-level headers looks strange to me under the smaller font of the tabs. Let's see if it looks better once we add introductory text.

kwalrath · 2018-03-30T21:22:07Z

src/tools/sdk/index.md

+## Install the SDK
+
+A package manager can help you easily install and update the Dart SDK.
+


Let's put the archive link here:

Alternatively, you can download zip files from the [Index of Downloads].

I've added both the archive and "build from source" links here.

kwalrath · 2018-03-30T21:23:59Z

src/tools/sdk/index.md

+{% include_relative _mac.md %}
+</div>
+
+Alternatives:


Let's delete this paragraph and the bulleted list that follows.

kwalrath · 2018-03-30T21:27:24Z

src/tools/sdk/archive/index.md

@@ -3,9 +3,9 @@ title: "Index of Downloads"
 description: "Download specific stable and dev channel versions of the Dart SDK, Dartium, and the Dart API documentation."
 permalink: /install/archive


Update the permalink to /tools/sdk/archive, and (wherever the breadcrumbs are defined) make the previous page be Dart SDK, not Install Dart.

I've renamed this page to "Dart SDK Download", with a short title of just "Download", so that we get this heading w/ breadcrumbs:

We have to be careful about how we refer to these pages. This title might be good, but we don't want to imply that it's the preferred way to download the SDK.

kwalrath

I forgot to put the big red X on this...

chalin · 2018-04-02T19:56:39Z

Changes complete and staging server refreshed.

kwalrath

We're really close! Due to GitHub weirdness, I think there might be double comments for some things...

kwalrath · 2018-04-02T20:01:01Z

src/tools/sdk/archive/index.md

  defer: true
 ---
+


Later this page refers to the "main Dart installation page". Let's just call it the "Dart SDK" page. We should also check for other references to that page.

We should also check for other references to that page.

I've swept the docs and made the necessary changes.

kwalrath · 2018-04-02T20:03:52Z

src/tools/sdk/archive/index.md

-description: "Download specific stable and dev channel versions of the Dart SDK, Dartium, and the Dart API documentation."
-permalink: /install/archive
+title: Dart SDK Download
+short-title: Download


Download -> Zip Files (in the title & short-title)
... or something else indicating that this isn't the primary download page.

How about Archive?

kwalrath · 2018-04-02T20:07:09Z

src/tools/sdk/index.md

+Don’t want to use a package manager? Other options are:
+
+* [Download the SDK manually](sdk/archive)
+* [Build the SDK from source][]


I'm afraid this bulleted list might tempt people away from package managers. How about:

...update the Dart SDK. Other options are [building the SDK from source] and [downloading the SDK as a zip file].

That way the download link is still easy to find (last thing in the paragraph), but not quite as tempting.

Good suggestion.

kwalrath · 2018-04-02T20:09:41Z

src/install.md

+
+Choose your platform.
+
+{:.card-grid}


It looks better, thanks.

kwalrath · 2018-04-02T20:10:15Z

src/install.md

+app in the Dart language, once you are ready to develop real apps, you need the
+Dart SDK.
+
+Install the Dart SDK for your platform.


Dart SDK -> SDK

kwalrath · 2018-04-02T20:10:56Z

src/install.md

@@ -5,30 +5,38 @@ permalink: /install
 toc: false
 ---

-Choose your platform.
+The [DartPad][]{: target="_blank"} is a great way to learn how to write a simple


The -> Although

kwalrath · 2018-04-02T20:11:21Z

src/install.md

-Choose your platform.
+The [DartPad][]{: target="_blank"} is a great way to learn how to write a simple
+app in the Dart language, once you are ready to develop real apps, you need the
+Dart SDK.


the Dart SDK -> an SDK

kwalrath · 2018-04-02T20:12:49Z

src/tools/sdk/index.md

- Looking for an older version?
-  Check out our [zip file archive](/install/archive) for
-  previous versions of the Dart SDK.
-
 ## What's in the SDK

 The SDK directory includes a `lib` directory for the


SDK directory -> Dart SDK

It seems weird to talk about an SDK directory, especially when some package managers put stuff all over the place. E.g. my copy of dart is in ~/homebrew/bin, which links to ../Cellar/dart/2.0.0-dev.43.0/bin/dart, which has bin and libexec directories (the latter of which contains bin and lib directories). I considered dropping the mentions of bin and lib, but on second thought they're kind of handy.

In general, many occurrences of "SDK" should perhaps be "Dart SDK". Some occurrences of "SDK" could perhaps be deleted ( e.g. "About release ~~SDK~~ channels and version strings").

kwalrath · 2018-04-02T20:25:43Z

src/tools/sdk/archive/index.md

@@ -40,7 +41,7 @@ production use.

 {% include_relative _archives_table.html channel="dev" %}

-## Direct download URLs
+## Download URLs


We should update the example URLs, either now or in a future PR.

I've made some updates to the example URLs. We can make more once 2.0 final comes out.

kwalrath · 2018-04-02T20:27:19Z

src/install.md

@@ -5,30 +5,38 @@ permalink: /install
 toc: false
 ---

-Choose your platform.
+The [DartPad][]{: target="_blank"} is a great way to learn how to write a simple
+app in the Dart language, once you are ready to develop real apps, you need the


delete "in the Dart language"
you are -> you're

chalin · 2018-04-03T16:16:48Z

Thank you for the very good suggestions. I've made the necessary changes and updated the staging server.

kwalrath

Just about to run out of charge on my mac, so I'll send these and finish later...

kwalrath · 2018-04-03T18:11:31Z

firebase.json

-      }
+      },
+      { "source": "/install/**", "destination": "/install", "type": 301 },
+      { "source": "/tools/pub/**", "destination": "/toosl/pub", "type": 301 }


toosl -> tools
(but why add this redirect? it breaks all the URLs under pub, e.g. https://dartlang-org-staging-1.firebaseapp.com/tools/pub/cmd/pub-get)

Oops, clearly not the desired effect. Changed to / was meant to be:

{ "source": "/tools/pub/installing", "destination": "/tools/pub/environment-variables", "type": 301 }

kwalrath · 2018-04-03T18:12:00Z

src/_data/side-nav.yml

@@ -39,8 +39,6 @@
    - title: "Dart VM"
      permalink: /dart-vm
      children:
-      - title: "Install Dart"


Where will people find this page?

We have a top-level sidenav entry named Install under RESOURCES. Why should Dart VM be singled out to have an install submenu item? If we have one for Dart VM, for sake of uniformity, we might as well have one for Web and for Mobile. Instead, I think that folks should be encouraged to go to the main install page in all cases. WDYT?

Ah, I thought you were deleting the one under RESOURCES.

kwalrath · 2018-04-03T18:12:59Z

src/tools/pub/installing.md

@@ -1,49 +0,0 @@
---


Why are we getting rid of this page?

Because we don't install pub. One installs the Dart SDK; the main pub page opens with:

You can use the pub tool to manage Dart packages. Pub is one of the tools that you get when you install the Dart SDK.

In think that that is all we need.

The rest of the pub "installing" page was actually only about environment variable configuration. Which is what I renamed to page to.

kwalrath · 2018-04-03T18:15:34Z

src/_includes/configure-path.html

@@ -1,21 +0,0 @@
-<div markdown="1">


Do we cover setting the path anywhere?

Whether / how one sets the path or not depends on (1) the technique used to install the SDK, (2) how the SDK is used and in which environment / shell it is used from.

For example, when using Homebrew under MacOS, one shouldn't adjust the path specifically for the Dart SDK. Doing so can lead to problem later on when Dart is upgraded and/or versions are switched.

Our previous instructions on how to set the path were incomplete at best, misleading in some cases.

Let's just mention adding the SDK's bin directory (or whatever) to your path, and leave it up to people to find the instructions. (We added the path info because some beginners would get confused when they installed Dart but couldn't run the commands.)

Where do you want this mentioned? (This particular file is just an include.)

(I'd suggest leaving any such mention for now and we can consider re-adding it, or directing folks to SO ... as the need arises. WDYT?)

I think we should mention adding the SDK's tools to your path in the /tools/sdk page, somewhere inside the "Install the SDK" section.

Oops, I didn't get the notice about this comment until now. I'll add it with my next PR.

Here it is: #740

kwalrath · 2018-04-03T18:18:01Z

src/dart-vm/tools/index.md

 toc: false
 ---

-When you [install](/install) the
+When you [install](/tools/sdk#install) the


Let's remove the link on "install".

kwalrath

Minor URL/redirect changes, then I think we're good to go!

kwalrath · 2018-04-03T21:11:06Z

firebase.json

@@ -1171,7 +1171,9 @@
        "source": "/dart-2.0",
        "destination": "/dart-2",
        "type": 301
-      }
+      },
+      { "source": "/install/**", "destination": "/install", "type": 301 },


I'm torn about whether to set up a separate redirect for the archive (/install/archive -> /tools/sdk/archive). I suspect that lots of people have links to the archive page, so it seems reasonable to take them to the page they want.

The only reason not to redirect /install/archive to /tools/sdk/archive is if we really DO want to force people to think — to look at the 3 SDK options and then hunt in the Dart SDK page for the archive.

I'm leaning toward redirecting /install/archive to /tools/sdk/archive, to avoid irritating the type of expert user who tends to use the archive.

leaning toward redirecting /install/archive to /tools/sdk/archive

That sounds reasonable.

FYI, we'll have both kinds of redirects. One for the archive link, and the other to catch the OS specific pages.

kwalrath · 2018-04-03T21:20:34Z

src/tools/sdk/index.md

+A package manager can help you easily install and update the Dart SDK.
+Don’t want to use a package manager? Other options are
+[building the SDK from source][] and
+[downloading the SDK as a zip file](sdk/archive).


sdk/archive -> /tools/sdk/archive (or archive)?

I somehow ended up with the path .../tools/sdk/, and then this took me to .../tools/sdk/sdk/archive, which was a 404.

I wonder (a) why it's possible to have the / at the end of the URL (there's a bug about this somewhere) and (b) how many similar possible 404s exist in this site.

Stange. I'm not seeing that. I've change the link to /tools/sdk/archive just in case.

Ah, the related issue is on site-webdev: https://github.com/dart-lang/site-webdev/issues/1418

Addresses #727 (comment)

chalin added the a.get-started Relates to Getting Started with Dart label Mar 30, 2018

chalin added this to the 2-beta2 milestone Mar 30, 2018

chalin requested a review from kwalrath March 30, 2018 20:22

googlebot added the cla: yes Contributor has signed the Contributor License Agreement label Mar 30, 2018

filiph approved these changes Mar 30, 2018

View reviewed changes

kwalrath reviewed Mar 30, 2018

View reviewed changes

chalin mentioned this pull request Mar 30, 2018

[Meta] Site changes for Dart 2 #637

Closed

63 tasks

kwalrath suggested changes Apr 2, 2018

View reviewed changes

chalin force-pushed the chalin-install-0330 branch from 1ad1318 to 2151fe8 Compare April 2, 2018 19:55

kwalrath reviewed Apr 2, 2018

View reviewed changes

chalin force-pushed the chalin-install-0330 branch from 2151fe8 to c4bd7d9 Compare April 2, 2018 21:21

chalin added 3 commits April 2, 2018 20:57

Update jQuery and other JS assets

e640f48

Refactor Install page before moving a copy to webdev

fcedcd4

Post-review edits

4a57e12

chalin force-pushed the chalin-install-0330 branch from c4bd7d9 to 4a57e12 Compare April 3, 2018 00:57

More post-review edits

67f7ca4

kwalrath suggested changes Apr 3, 2018

View reviewed changes

Update redirect, and other page tweaks

41627d2

kwalrath approved these changes Apr 3, 2018

View reviewed changes

Final edits

b96d676

chalin merged commit 9598b93 into master Apr 3, 2018

chalin deleted the chalin-install-0330 branch April 3, 2018 21:49

chalin added a commit that referenced this pull request Apr 4, 2018

Add reminder to add SDK bin to PATH when manually installing SDK

f46bdff

Addresses #727 (comment)

chalin mentioned this pull request Apr 4, 2018

Reminder to add SDK bin to PATH when manually installing SDK #740

Merged

kwalrath pushed a commit that referenced this pull request Apr 4, 2018

Add reminder to add SDK bin to PATH when manually installing SDK (#740)

ce643d1

Addresses #727 (comment)

		@@ -0,0 +1,33 @@
		#### Install using a setup wizard
		{: style="margin-top: 0"}

		## Install the SDK

		A package manager can help you easily install and update the Dart SDK.

		@@ -3,9 +3,9 @@ title: "Index of Downloads"
		description: "Download specific stable and dev channel versions of the Dart SDK, Dartium, and the Dart API documentation."
		permalink: /install/archive


		Choose your platform.

		{:.card-grid}


		Choose your platform.

		{:.card-grid}

Refactor Install page before moving a copy to webdev #727

Refactor Install page before moving a copy to webdev #727

Conversation

chalin commented Mar 30, 2018

filiph left a comment

Choose a reason for hiding this comment

kwalrath left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwalrath left a comment

Choose a reason for hiding this comment

chalin commented Apr 2, 2018

kwalrath left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chalin commented Apr 3, 2018

kwalrath left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwalrath Apr 3, 2018 • edited Loading

Choose a reason for hiding this comment

chalin Apr 3, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwalrath left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chalin Apr 3, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwalrath Apr 3, 2018 •

edited

Loading

chalin Apr 3, 2018 •

edited

Loading

chalin Apr 3, 2018 •

edited

Loading