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

Rewrite Vagrant tutorial to be less confusing to newcomers (Step 4) #802

Open
JLKwong opened this issue Jan 20, 2021 · 1 comment · May be fixed by #815
Open

Rewrite Vagrant tutorial to be less confusing to newcomers (Step 4) #802

JLKwong opened this issue Jan 20, 2021 · 1 comment · May be fixed by #815
Labels
ready for VI

Comments

@JLKwong
Copy link
Member

JLKwong commented Jan 20, 2021

Problem

In Step 4, the Vagrant tutorial, descriptions alluding to how to use Vagrant are described before the step for installing Vagrant. Additionally, several phrases and formatting make it unclear when to install Vagrant, or what to do before installing Vagrant. If I had to pick the 'largest obstacle' for me completing the steps up to this point, it was this because I have little to no background with Git and Vagrant.

Steps to reproduce the problem

N/A

Screenshots

image
image
image
image

Proposed solution

Possible (not the only) solutions for the Introduction section:

  • Start the introduction with a sentence that states that we need to prepare our PC first (setup the cli repository, enable virtualization on our computer, and install VirtualBox), then install Vagrant, OR
  • Remove the hyperlink for Vagrant's home page with the download button. (This will prevent readers from installing Vagrant before moving to the next section that finally tells the reader they need to do preparation before installing Vagrant.) OR
  • Move that description to a (new or pre-existing) section after the text that reads that preparation is needed before installing Vagrant.

Possible (not the only) solutions for the Stay in the Right Directory section:

  • Delete ALL text of 'Vagrant', AND add instructions that describe the context for cloning the repo (and what git clone does). (This will prevent the reader from worrying whether they should have installed Vagrant yet. This also clarifies why we're suddenly cloning a repo or what the commands are doing.) OR
  • Create a new section Cloning GitHub Files with instructions for cloning the GitHub repo (plus context for cloning the repo and what git clone does), AND move the Stay in the Right Directory section containing the rest of the information to somewhere after the section for the Vagrant install (the rest of Stay in the Right Directory section information is quoted below):

A lot of Vagrant commands require us to specify a target machine. We can also run those commands from a directory with the target machine’s Vagrant File. Otherwise, you may encounter an error like "A Vagrant environment or target machine is required." Please go to the directory that contains our Vagrant file:
Windows users should do the following: cd C:\Users\%USERNAME%\cli
macOS or Linux users should do the following: cd Desktop

@BryanGazali
Copy link
Member

BryanGazali commented Jan 28, 2021

We'll approve this issue, but it does seem like a fairly extensive solution to complete. We'll let you try to do this but if this ends up being too hard to complete and you want to move onto something else, that's ok.

@BryanGazali BryanGazali added the ready for VI label Jan 28, 2021
JLKwong pushed a commit to JLKwong/JLKwong.github.io that referenced this issue Feb 3, 2021
@JLKwong JLKwong linked a pull request Feb 3, 2021 that will close this issue
JLKwong pushed a commit to JLKwong/JLKwong.github.io that referenced this issue Feb 3, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
ready for VI
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants