Planet Tutorial (Step 4) Improvements and Clarifications

[johnmdrake1]

Problem

Certain Sections of the Planet Tutorial page used in step 4 could use some clarifications and additions. Potential problems are as follows:

• Steps 2 and 4 have to do with Docker and Planet, but step 3 breaks from this to teach about GitHub and Markdown. It may do well to have a bit more explanation on what steps to take to get Planet back up and running at the beginning of step 4, as aspiring Virtual Interns may have rebooted their computers or not know the full steps of getting their planet up and running again, even though all that should be necessary is to cd into the planet and vagrant up prod .

-There should be some clarity in what should be done with the running Planet when away from the computer and it may shutdown or die. A note indicating whether it is ok to keep that terminal window open with the planet running indefinitely, or if it is safer to run vagrant halt prod and/or vagrant suspend prod when away from the computer and not working on the Virtual Intern steps would put some like myself at ease.

-I got an infinite loading screen and had to destroy and create a new community personally. Following the troubleshooting steps 4 and 3 on the Planet Configurations was sufficient for me, but in Gitter chat I was advised to wait until my new community was approved before proceeding with step 4 and proceeding to step 5 in the meantime. If this is correct information, this should be stated here. I did not know whether I had to follow all of the steps of part 2 again, or just the ones listed in the aforementioned troubleshooting steps.

-When uploading the resources, it is stated that everything does not have to be perfect. What is unclear, however, is what to put in the "Open Which File" field(I just put the filename, and it worked), and whether "File Downloadable" should be checked. On the "Open" drop-down, there are several options, as seen here

Some of these options are straightforward and obvious, like MP3 for the Opposite Song , but for the Feelings PDF I chose "Just Download", because I did not know what PDF.js was or if it would work.

For the MP4 portion, there are 3 options:

I chose "Native Video Player", but some guidance on which choices are best suited for each file type may make new Aspiring Virtual Interns less confused.

-When taking the course, the final question desires screenshots, as they are helpful in providing feedback. I could not locate a file attachment button, so I used a private, hidden Imgur link to my album of screenshots relevant to my feedback. If these should be hosted in a specific place, or posted in the Gitter chat, this should be specified.

-When instructed to Manage Sync , this appears for a brief moment;
but nothing seems to follow confirming the sync is completed. This should be noted, unless there is a message and I did not wait long enough.

-Various ways things could be rewritten, such as the use of the words "run" and "undergo" being used interchangeably when referring to executing terminal commands.

Steps to reproduce the problem

As far as my seemingly common issue with having to destroy my Planet and configure a new one, I questioned if the version of Planet I used for my configuration had to do anything with this. My error was this screen and weird interface:

Once I destroyed my Planet and configured a new one, I noticed I was still configuring using my version 0.7.33, and was concerned it would again not work, but it did. Afterwards, I went to my manager page and noticed the following:

The Nation version was ahead of my local version of Planet. This raised my suspicions further that version had something to do with my login loop, but I cannot confirm, it is just a theory of mine.

Once following the upgrade step further down in the tutorial, the versions matched, but I still wonder if their initial discrepancy had something to do with it.

Screenshots

N/A, see screenshots above

Proposed solution

Much of this requires verification from a member before anything can be rewritten, as I do not want to add any misinformation to the tutorial whilst trying to do the opposite.

One thing I feel I am very skilled in is writing in a clear and unambiguous manner. There are several existing sentences I can reword to not change meaning, but simply make clearer and sound better, while using proper grammar. I would love to do so on this page and others, if given permission to proceed.

If am only given permission to branch, fix, and file a pull request on a few of these issues, I understand. I hope this is a worthy issue to raise, as step 4 gave me the most trouble.

[lmmrssa]

There is already

Please go to http://localhost:3100 or run vagrant global-status in the command line to see if your community Planet is currently running. If not, please cd into planet directory in your local machine and run vagrant up prod.

on Step 4 to explain you might require to start vagrant again.

Regarding planet configuration, if you destroyed vagrant that means you are back on step 2 so it is already mentioned there to post configuration screenshot for new configuration (planet).

Regarding registration issue, there could be different reason for it, and during 10 steps we do not try to spend more time on debugging your issue as that cost a lot of time and having fresh installation is simple and easiest step to fix it. Version is just to make sure you are on latest update as we are continuously releasing new version and you will come to upgrading your system on one of 10 steps.

For resource creation we have mentioned that everything does not need to be perfect as you are just looking over feature and that record will not be used by others. So we are not putting lot of information about each part of system, that will be a big manual on its own. But if you can improve wording on this section then please propose the changes you will make we will check if that sounds good.

@johnmdrake1 hoping i tried to answer all your questions.

[johnmdrake1]

Right, it is stated that a new screenshot is required when you make a new configuration. My concern was that it is clear enough that all that has to be done is a new configuration, not repeat the entirety of step 2. Some may think they have to redo everything(docker, etc..) and overcomplicate things when all that is truly needed is a reregistration.

The Version note was mainly in regards to something that could be added as a sidenote saying it is nothing to worry about if your version is different for now. It could also help some people troubleshoot because they will know it is not the version that is the problem.

I completely understand what you are saying about resource creation, however. The only issue is that step 4 says you need to go to your library and make sure everything is viewable. If they chose the wrong open method for that filetype(i.e. wrong mp4 player) the Aspiring Intern will not be able to view their uploaded resource. So I understand that it is mainly to demonstrate and not meant to be perfect, the only potential downfall is when it comes to the files and how they are opened.

I will improve wording and put in a pull request with my changes once I am finished. Thank you, I will update when done.

[johnmdrake1]

@Immrssa I am creating a branch with the proposed wording changes now, but will follow your guidance in your comment about what does not need to be changed.

[ghost]

One could also add that the user can turn off the virtual machine from the VirtualBox GUI. See screenshot below: