Skip to content

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

Open
@JLKwong

Description

@JLKwong

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions