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.

Sign up for GitHub

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

Jump to bottom

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

Closed
stevetraut opened this issue Jul 30, 2020 · 6 comments
Closed

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

stevetraut opened this issue Jul 30, 2020 · 6 comments
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Unreleased

Comments

@stevetraut
Copy link

stevetraut commented Jul 30, 2020 •
edited
Loading

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
@cagedmantis cagedmantis added the Documentation Issues describing a change to documentation. label Jul 30, 2020
@dmitshur dmitshur added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jul 31, 2020
@stevetraut
Copy link
Author

I have a branch with changes in progress.

@gopherbot
Copy link
Contributor

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
content/static/doc: improve getting started docs with install topic a…
fb84a6e 
…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

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

@dmitshur
Copy link
Contributor

dmitshur commented Oct 8, 2020 •
edited
Loading

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:

@dmitshur dmitshur reopened this Oct 8, 2020
@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Oct 8, 2020
@dmitshur dmitshur mentioned this issue Oct 8, 2020
Closed
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/291692 mentions this issue: content/doc: update install-source.html with changes from main repo

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/291709 mentions this issue: doc: remove install.html and install-source.html

gopherbot pushed a commit that referenced this issue Feb 16, 2021
@rsc
doc: remove install.html and install-source.html
626ef08 
These live in x/website/content/doc now.
The copies here just attract edits that have no actual effect.

For #40496.
For #41861.

Change-Id: I2fdd7375e373949eb9a88f4cdca440b6a5d45eea
Reviewed-on: https://go-review.googlesource.com/c/go/+/291709
Trust: Russ Cox <rsc@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
@golang golang locked and limited conversation to collaborators Mar 28, 2022
passionSeven added a commit to passionSeven/website that referenced this issue Oct 18, 2022
@passionSeven
_content/doc: update install-source.html with changes from main repo
7879f09 
Copied from Go ff0e93ea3, deleted there in CL 291709.

Fixes golang/go#40496.
Fixes golang/go#41861.

Change-Id: Idb04706ea46b97be69fbeb98637c7ac2e4b54729
Reviewed-on: https://go-review.googlesource.com/c/website/+/291692
Trust: Russ Cox <rsc@golang.org>
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Unreleased
Development

No branches or pull requests
5 participants
@cagedmantis @dmitshur @ianlancetaylor @stevetraut @gopherbot