1. Principles and practices, project management

This week the assignment is to

  • Plan and sketch a potential final project.
  • Complete a Git Tutorial
  • Build a personal FA2020 website in the class archives…describing you and your final project

Sketch for a potential final project

I want to build an interactive installation that distillates ocean water to make water and salt.

It aims to help children (8-15 year old) understand about chemical engineering - what a continuous process is, and what are the parameters when controlling it.

The details are described in this page

Git

I use git through Sourcetree at work so I am familiar with the concept. However, I never installed or using the git through command.

At first, I opened Terminal and tried out several simple commands such as

ls lists what’s inside a folder
pwd shows me the current directory
cd changes directory cd ~/Documents takes me to Documents folder
. defines layer of folders. cd .. takes me to 1 layer above
man to get help. man list presents help regarding list

Then I proceeded to set up git in my computer. I was worried if setting up another repository would mess up with the one at work. I learned that setting it up only changes the username and email address shown up when I do a commit. And I can change it later. global in git config -–global user.email “jSmith@mail.com” means setting up for all my repositories so if I want separated ones I need to get rid of that.

I thought I would already have SSH key since I use it at work. But it turned out that I didn’t! Apparently, we might be using SSL instead of SSH.

Note

Both SSH and SSL are security protocols to keep personal information private during data transmission and secure communication over the Internet and public networks. They save similar purpose, but they have different use cases. SSH is often used with GUI (graphic user interface). SSL/TLS, on the other hand, is used for CUI (character-based user interface).

It seems that git is pre-installed on my Macbook. So I generated SSH, receiving my private key while saving the public key on FabAcademy’s repository. The password I put is used to match the public key and my private key.

I cloned the FabAcademy repository to mine using this command:

$ git clone git@git.fabacademy.org:fabacademy2020/mylabname/mystudentnumber.git

It says that the authentification was not established, but the folder copied from the repo was confirmed on my desktop, so it was actually completed without a problem.

However, I encountered an issue that I’m asked the password everytime when I do git pull or push.

To solve it, I added and opened ssh config file through terminal with:

$ cd ~/.ssh  
$ touch config  
$ open/.ssh/config

I typed this in the config file, and after being asked passwork for my first pull, it never asks me again after!

Host *
    UseKeychain yes
    AddKeysToAgent yes

Making my site

I installed Homebrew, Python, pip in order to download Mkdocs. I had some issues here. - The Python pre-installed on Macbook is a dummy software, so I installed Python on my own. - The Python downloaded from webpage is stored in a different path. Doing in in terminal makes it a lot easier. - Since the Python I installed was version 3, I had to install pip 3 instead of pip

After some struggles, everything was installed!

My questions answered by super Kamakura instructors:

  • Q. What is Homebrew?

  • A. Homebrew is a tool to do version control for packages. Although usually you can download dmg files to install new things, there are times when the files are not dmg and there are multiple of them (especially Linux to Mac), Homebrew is used to install them.

  • Q. What is pip?

  • A. A tool to install packages on Python.

I tried to set up a test server (so I can see the changes I make before I push everything onto my repo), but the page I expected didn’t show up because “material is not correctly installed”.

Material for MkDocs provides design themes for Markdown pages. The error occured since in mkdocs.yml, it mentions name: material while material was not installed.

I searched for “mkdocs material” to install from this page. And… TADA!!!!

ctrl + C is to quit test server.

I opened my yml file using Visual Studio Code since I use it to edit json at work. I made some changes (site name, color, social media links) to mkdocs.yml and edited my student agreement.

To push changes to the repo:

Step 1: git add . + enter
Step 2: git status + enter (read message of what files are being staged, if there are problems with branching, etc)
Step 3: git commit -m “(some message)” + enter…not just git commit + enter
Step 4: git push + enter.

And…

All changes were reflected!!

I wondered why my page only showed up being “404 error” in the morning before these changes.

Again, according to the amazing Kamakura instructors, this “gitlab-ci.yml” did the magic by defining what I want the server to do. He warned me NOT to delete it. He deleted it by mistake last year and he spent a long time trying to figure out the bug.

Documentation

I edited markdown(md) files on Visual Studio Code and used test server to check the changes. It was very convenient that the changes are reflected immediately.

I downsized my pictures using onlinejpgtools

Downsizing is necessary since you don’t want the images to take up tremendous space on git since the pricing for using git is based on the data size. And the images are clear enough after downsizing.

Later I had some issue with git push. I tried to revert some changes and then I editted some files. When I tried to commit those, there appeared to be conflict. I saved the files in local, did git reset, and hard push. Then I pasted my local files into the repository and succeeded pushing.

I also learned that to edit the title of each session, I only need to edit the text in each md files. The pre-set page for Assignments was like 1. , 2. Project management, 3. 3D aided… However, 1&2 was combined as 1 this year. So I deleted the existing md file named week2, edited the text of week 3’s md file into “2. 3D aided…” and it worked! What a simple tool Mkdocs is!

Trying out other tools

Image compress

xnconvert: I liked it since it does compression by batches. And that you have many options on how you want to edit the files, and that you can choose to delete the original images.

Web development

Atom: A text editor. I saw that they have many extensions. However, since I am already done most of the editing of my documents, I didn’t get the chance to try out them. However, I liked that they have spellcheck pre-installed. I heard that VS Code also has it as an extension.
In this screenshot, Atom is the left while VS Code is the right. You can see Atom tells me “editting” is wrong.

Also it has words prediction.

Dillinger: an online editor that shows you immediately how it turns out to be. It is very convenient! However it doesn’t reflect changes on underline, color, font, etc.

Admonition: An extension to add summaries, notes, hints or warnings.
I added this line to my mkdocs.yml file:

markdown_extensions:  
    - admonition

When editing my file, at first I only added “!!!” in front of my code and it didn’t work.

Then I discovered that I needed to write !!! note in front. I missed “note”.

!!! note "# 1. Principles and practices, project management"
This week I worked on defining my final project idea and started to getting used to the documentation process.

It worked!

Project management concepts

Here are my understandings to some project management concepts.

  • Supply side time management

This is the opposide to “Demand side time management”. The idea is to understand how many hours each week I can spend on the weekly assignments, and plan out the hours I can spend on working on the assignment, and documenting it. When I work on them, I need to be aware of the time I have for it all the time.

  • Triage

Triage is used in hospitals to identify the priority to cure patients especially when they don’t have enough resource for everyone. Those who can’t be helped are “abandoned”, those who can be saved but are in critical situation need to be cured first than those who aren’t in critical situations.

Task wise, it is needed to identify the tasks that can no way be accomplished, tasks that are of high emergency, and tasks that can wait. And time should be managed based on that.

  • Spiral development

Spiral development starts with a small set of requirement and goes through each development phase adding more sets of requirements. Functionality for the additional requirement is added in every-increasing spirals.

This ensures the fundamental requirements are cleared first, and extra functionalities can be added based on the time one has.

Borrowing the awesome drawing of Rico, to make a bike, this is an example how the spirals can be separated into.

The first spiral is about the basics - the frame, tires, pedals, and handles so the bike moves.

The second spiral is about safety - the backlight for darkness.

The third spiral is about speed - modifying the frame to increase speed.

The fourth spiral is about decoration - painting the body etc.

The fifth spiral is to perfect the whole bike.

  • Parallel development

The opposite of “serial development”.

Borrowing the awesome drawing of Rico again, to build a robot, instead of building one part only after one is finished, all parts are built at the same time parallely.

This method reduces scheduled working time, and there is less chance of reworking since you can revisit the design of a specific part when it is still not completed.

Student agreement, and Fab Charter

This is my student agreement.

It is also stated in Fab Charter that the users responsibilities are:

safety: not hurting people or machines
operations: assisting with cleaning, maintaining, and improving the lab
knowledge: contributing to documentation and instruction

My documentation would not only be a proof of me completing the assignments, but also a contribution to the Fab network to knowledge accumulation.

After Week 1

  • Not only did I get to “complete” my assignment, I was also able to “understand” how many things work. The git master at Kamakura - Tsuchiya-san really helped me a lot and I would like to thank his patience for answering my endless questions.
  • I think I did a good job on project management. I was able to complete my assignments first with tools I am more comfortable with, and then proceed on trying out other tools.
  • I have to say I was “allergic” towards programming before because I thought the concept behind is very abstract. But this week I discovered that it is more concrete than I thought, and it gives feedbacks right away to what I am doing. So I actually found it fun and felt the sense of achievement I receive when making tangible things.