Participant Development Environment - Inconsistency in Directory Structure

cmlccie commented 7 years ago

Lab-ID: Various

When participants are learning to code (and even if you already know how), it is important that we be crystal clear on 'where you should be' and what files you should working on/with. We have multiple places throughout the labs where we provide path instructions, and they aren't all consistent (a few specific screen shots are included below). Additionally some of our file and folder naming (most notably the virtualenv folder name) causes some confusion.

Screenshots

The 'recommended' code structure in dCloud... cisco_devnet_learning_labs

...isn't used consistently throughout the modules. cisco_devnet_learning_labs

...which leads to consistency participant issues like:

What command do I use to activate my virtual environment?
What is the path to the file that I should be editing?
When combined with issues like https://github.com/CiscoDevNet/devnet-express-dna-issues/issues/21 , these inconsistencies cause confusion and scripting errors (participants edit one file, but are actually trying to execute the same file in another folder).

Intuitive folder names

Some participant confusion arrises from how we name some things - most notably the naming of our virtual environments mycode and the devnet-code-samples folders.

Q: Where is 'my code' (meaning the files I have written, edited and contributed to) stored? A: One might think in the mycode folder, but it is actually stored in the devnet-code-samples.

Q: Where do the packages that I downloaded and installed via pip install (other peoples code) get stored? A: In the mycode folder. 🤔

Recommendation

We should define a simple but standardized folder structure (for the purposes of these events). Participants may choose to deviate (and that is ok - they can then adapt the instructions to fit 'their environment'), but at least our documentation would be consistent and for those that follow the instructions... Everything should work consistently.

Please address these consistency issues however suits DevNet best. My inputs:

Identify and recommend an easily-referencable folder where 'the folder for all of our event content' should live. Could be the system root or the users home folder (the user's home folder is preferable to prevent permissions issues).
Consistently name and reference the top-level folder (could be 'dev' or 'Code' or whatever - recommend lowercase and short).
Define a consistent and intuitive folder structure within this top-level folder (perhaps consider that instructors and participants might host / attend different DNE tracks).

Examples:

Top Level Folder:

Linux: ~/dev
Windows: %HOMEPATH%\dev

Potential Folder Structure(s):

~/dev
|--venv
   |--dna
   |--collab-cloud
|--code
   |--dna
   |--collab-cloud

~/dev
|--dna
   |--venv
   |--code
|--collab-cloud
   |--venv
   |--code

austinMarcos commented 7 years ago

In Friday triage meeting, with input from Chris L. decided that this is an issue that we should resolve now while we are in the process of creating a new pod image.

armartirosyan commented 7 years ago

I believe proposed folder structure is ideal solution to our problem.

~/CiscoDevNet          <-- Root directory
|--venv                <-- Folder containing virtual environments for different tracks
   |--dna
   |--cloud-collab
   |--dci
|--code                <-- Folder containing code samples for different tracks
   |--dna
      |--devnet-express-code-samples 
   |--cloud-collab
   |--dci

If there are no objections, I will go ahead and make changes in the DNA track

cmlccie commented 7 years ago

That structure looks good to me! The only modification or input that I would give would be to not add the devnet-express-code-samples folder/repo underneath the dna folder, but rather make-it the dna folder by cloning the repo to the dna folder name - like so:

git clone https://github.com/CiscoDevNet/devnet-express-code-samples.git dna

This shortens path names, and I feel it is a little cleaner / clearer.

armartirosyan commented 7 years ago

@cmlccie @austinMarcos Should this change be implemented before DevNetExpress event in Las Vegas or after? Below items need to be updated

Instructions in all labs
Screenshots
Slide decks

cmlccie commented 7 years ago

The DNA track isn't being offered at CLUS (just CC and DCI); however, it would be good to get this new 'standard' over to the other track creators to use in those tracks. It would be good to start off these tracks with the standardized folder structure - if possible.

hpreston commented 7 years ago

This makes sense to me and I agree it's a confusing issue. Having a standard will be great. We will implement in the DCI track that is in development now.

cmlccie commented 7 years ago

Just to confirm, we are looking at the following:

Last login: Sat May 20 12:04:49 on ttys001
~ $ mkdir -p ~/CiscoDevNet/venv

~ $ mkdir -p ~/CiscoDevNet/code

~ $ cd ~/CiscoDevNet
CiscoDevNet $ virtualenv -p python3 venv/dna
<-- Output Omitted -->

CiscoDevNet $ git clone https://github.com/CiscoDevNet/devnet-express-code-samples.git code/dna
<-- Output Omitted -->

CiscoDevNet $ tree -d -L 3
.
├── code
│   └── dna
│       ├── LM-1201
│       ├── LM-4201
│       ├── LM-4302
│       ├── LM-4402
│       ├── LM-4502
│       ├── LM-4602
│       ├── LM-4702
│       ├── LM-4802
│       ├── LM-4901
│       └── NWPLab
└── venv
    └── dna
        ├── bin
        ├── include
        └── lib

17 directories

Which produces nice, intuitive and relatively short relative paths like: ~/CiscoDevNet/code/dna/LM-4201/

Correct?

hpreston commented 7 years ago

@cmlccie one thing I've asked for the code samples on DCI is that after the "LM-XXXX" we include a short description of what the module is. Numbers are great to verify, but can be a pain if you don't intuitively know them. So what I've asked for would be something like this..

LM-5501 intro-aci
LM-5551 intermediate-aci

Any problems with that small deviation?

cmlccie commented 7 years ago

@hpreston , I completely understand... When looking at the LM-xxxx folders, you don't really know which one is which (was also an issue with the Modulexx naming / numbering scheme).

My input on the names you describe would be to:

Keep the names as short as possible (so we don't get the crazy long path names that we have seen with the DNA track).
Don't have spaces in the folder name; otherwise, people have issues working with with them - escaping the spaces or having to include quotes (sure you can just hit tab in most Unix/Linux shells, but not everyone knows this and it can cause some minor struggles for people who are just getting started).

So, something like:

LM-5501-intro-aci
LM-5551-intermediate-aci

Is probably ok. However, whatever we do, it would be good to standardize (and we just did change the folder names in the DNA track). 😬

Note that WWSE just contributed some funds to DevNet to help source an additional contracted Tech Writer. Maybe they can help us with all of these documentation revisions. 😎

hpreston commented 7 years ago

@cmlccie good points... we'll work them into the updates.

austinMarcos commented 7 years ago

+1 on Armen's proposed structure:

~/CiscoDevNet          <-- Root directory
|--venv                <-- Folder containing virtual environments for different tracks
   |--dna
   |--cloud-collab
   |--dci
|--code                <-- Folder containing code samples for different tracks

+1 on adding short descriptions to code samples folder names for the Data Center track.

+1 on 'Don't use spaces in the folder names'

@cmlccie I agree that although we are not presenting a DNE for DNA at CLUS 8-) , the week leading up to CLUS would be a good time to update the DNA pod's directory structure (and labs and slides). One advantage is that there are no DNExpress events happening during that week of June 19-23. I'll coordinate with @armartirosyan and @ecorban , who were already looking at updating the DNA pod (CiscoDevNet/devnet-express-dna-issues/issues/41). If not that week, then the week of July 3.

austinMarcos commented 7 years ago

Based on conversation in DCI scrum today re path for virtual environment folder

~/CiscoDevNet          <-- Root directory
|--venv                <-- Folder containing virtual environments for different tracks
   |--dna
   |--cloud-collab
   |--dci-py2
   |--dci-py3
|--code                <-- Folder containing code samples for different tracks
   |--dna    <--image on pod prepped with this as root of samples
   |--cloud-collab
   |--dci

cmlccie commented 7 years ago

Following past and recent observations from DNE events, we need to have a meeting to discuss at a higher level the end-to-end participant workflow. Tools used, recommended folder structures, and instructions provided all contribute to the participants journey and experience with engaging with these labs and learning track.

I have tagged the open issues related to the participants Development Environment, and I will schedule a call to discuss.

austinMarcos commented 7 years ago

The folder structure in the code samples directory was modified, but the following lab needs to have the instructions and screenshots (of the command line) changed:

https://learninglabs.cisco.com/tracks/devnet-express-dna/devnet-express-np-rest-apic/05-apic-04-mission/step/1

Also, verify that the changes appear in the DCI track:

https://learninglabs.cisco.com/tracks/devnet-express-dci/devnet-express-np-rest-python/04-rest-05-mission/step/1

armartirosyan commented 7 years ago

I removed all inconsistent folder structures and replaced with agreed format. The changes have been pushed to issue19 branch and have been published to stage LLs https://learninglabs.cisco.com:8867/tracks/devnet-express-dna.

If approved, I will issue pull request and will merge it with master branch.

Thanks

annegentle commented 6 years ago

@austinMarcos Can this issue be closed?

cmlccie commented 6 years ago

I do believe they implemented the changes... Though the directory structure is less than optimal. Participants have to move in and out of their code folder (or use relative or absolute path references) to work with their virtual environments. As part of the primer and track re-working, I would recommend the following structure. From seeing the use at the events (and general Python best practices), the best structure for the participants is to co-locate the virtual environment directory within the project root.

This would simplify the setup instructions and subsequent UX in working in the track.

At a macro-level the folder structure could look like so:

~/CiscoDevNet                <-- Root directory
|--tracks                    <-- Folder containing project/repository roots
   |--cc                     <-- Friendly folder name for the cloned repository
      |--.gitignore          <-- Update .gitignore to exclude the venv folder from inclusion in the repo
      |--requirements.txt    <-- PIP requirements file to manage track dependencies
      |--venv                <-- The virutal environment for this track; created with python -m venv
   |--dna
   |--dci

cmlccie commented 6 years ago

This way we could simply instruct participants to work out of the project root, and provide instructions relative to their project folder.

Activate your virtual environment?

source venv/bin/activate

Run a script?

python LM-XXXX/myscript.py

etc.

annegentle commented 6 years ago

Geez, yes, I hadn't realized it wasn't already this way. Agreed. We'll see what we can do in the next release set.

annegentle commented 6 years ago

@cmlccie I'm not entirely sure how to make these changes. Are these changes in dCloud images?

Also, help me understand what type of user would have cc, dna, and dci folders? Are many people completing all three tracks, or is this for image re-use purposes?

annegentle commented 5 years ago

This has been resolved in the DNAv3 work.

CiscoDevNet / devnet-express-dna-issues