Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/website: Improve "getting started" experience with simplified install steps and tutorials. #40496

Open
stevetraut opened this issue Jul 30, 2020 · 4 comments

Comments

@stevetraut
Copy link

@stevetraut stevetraut commented Jul 30, 2020

This is an issue requesting additional documentation.

The current Getting started topic includes information that is likely not needed (at least, at first) by most new users. A new user is likely not installing multiple Go versions, nor are most likely to be concerned about system requirements. We could break up the topic's information to help new users focus on what's essential to begin.

We could make the following changes:

  • Streamline the install experience to include merely a download link for the installer and instructions for installing.
  • Detect user OS and present only the information they are likely to need (but give easy access to the rest).
  • Move other information from the existing Getting started into a separate topic where it can be found by those users who need it.
  • Add a very brief tutorial that introduces a small amount of code, a few Go commands, and a few key concepts. We can then link to this tutorial from the install topic.
  • Add a longer tutorial that introduces concepts and code fundamental to programming generally (functions, loops, data types, and so on). Sections of the tutorial would be connected by a narrative thread.

@andybons @dmitshur

@gopherbot gopherbot added this to the Unreleased milestone Jul 30, 2020
@stevetraut
Copy link
Author

@stevetraut stevetraut commented Jul 31, 2020

I have a branch with changes in progress.

@gopherbot
Copy link

@gopherbot gopherbot commented Aug 3, 2020

Change https://golang.org/cl/246499 mentions this issue: content/static/doc: improve getting started docs with install topic and tutorials

gopherbot pushed a commit to golang/website that referenced this issue Aug 31, 2020
…nd tutorials

The existing install topic includes content that is likely not needed by
most new users, including system requirements, content on installing
multiple versions, and so on. This change separates the most common install
case content into its own topic and moves some of the less commonly used
content into a separate topic.

This change also includes an introductory tutorial that might be useful for
new users, particularly those coming from a different language. A second
multi-part tutorial continues the introduction with fundamental programming
topics connected by a narrative thread and featuring links to other related
parts of the docs.

This change includes:

- A simpler "Download and install" topic that replaces Getting started.
Topic is designed to help users focus on what they need for a given OS.
- A new "Managing Go installations" topic that holds content about
installing that is likely not in the most common workflow (including
uninstall, multiple versions).
- A minor change that adds a link to the install-source topic.
- A single-page Hello World tutorial.
- A multi-part tutorial that introduces fundamental programming concepts
from a Go perspective (functions, loops, errors, slices, maps, and so on).
- An index file that lists the tutorials.
- CSS to style "Note" sections, tabbed sections, table, and highlighted
code.
- A JavaScript file with code for the install page.

This change also creates on golang/website a version of install.html and
install-source.html, which would be deleted from the golang/go repository
(effectively moving the files).

For golang/go#40496

Change-Id: I2af6f5fbbcfcf887c8698919666155cc40ce0d03
Reviewed-on: https://go-review.googlesource.com/c/website/+/246499
Reviewed-by: Russ Cox <rsc@golang.org>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@stevetraut
Copy link
Author

@stevetraut stevetraut commented Oct 7, 2020

I think this is closed with the commit on 8/31.

@dmitshur
Copy link
Member

@dmitshur dmitshur commented Oct 8, 2020

I found that there's a little more that needs to be done here.

Specifically, CL 246499 copied doc/install.html and doc/install-source.html files from the main repository. We need to also delete those files from the main repository, otherwise contributors may accidentally send their changes to the old copy, not realizing the file has moved to x/website.

It seems there were changes to doc/install-source.html since then that'll need to copied over:

  • CL 250997 added the linux/riscv64 pair, but it's not there in the x/website copy
  • CL 254740 added new GOOS=ios value, but it's not there in the x/website copy
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
You can’t perform that action at this time.