2. Project management¶

The goal of this week was to go through git tutorials and learn the project documentation process.
Build a website (using mkdocs templates provided by the FabLab) describing us and our final project.

Challenges¶

To be honest, this week’s assignment was going to be the most difficult assignment for me as I had no prior knowledge of git and web development.
But I like challenges, so, I watched many tutorials on Git, Python, and mkdocs.

Version control systems¶

About version control¶

Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later.

If you want to keep every version of an image or layout, a Version Control System (VCS) is a very wise thing to use. It allows you to:

Revert selected files back to a previous state.
Revert the entire project back to a previous state.
Compare changes over time.
See who last modified something that might be causing a problem, who introduced an issue and when, and more.

Using a VCS also generally means that if you screw things up or lose files, you can easily recover. In addition, you get all this for very little overhead.

The various types of the version control systems are:

Local Version Control System
Centralized Version Control System
Distributed Version Control System

Local Vesion Control System¶

Local version control system maintains track of files within the local system. This approach is very common and simple. This type is also error prone which means the chances of accidentally writing to the wrong file is higher.

Centralized Vesion Control System¶

In this approach, all the changes in the files are tracked under the centralized server. The centralized server includes all the information of versioned files, and list of clients that check out files from that central place.
Example: Tortoise SVN

Distributed Vesion Control System¶

Distributed version control systems come into picture to overcome the drawback of centralized version control system. The clients completely clone the repository including its full history. If any server dies, any of the client repositories can be copied on to the server which help restore the server.

Every clone is considered as a full backup of all the data.
Example: Git

Getting started with GIT¶

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.
I started with downloading the software from Git website.

After successful installtion, I setup my account using two git commands -
“git config –global user.name” and “git config –global user.email”

Next step was to setup SSH key using “ssh-keygen -t rsa -C “your_email@example.com”“

Then copied and pasted the key into my fablab github account. This is an important step for communication between your local repository and remote repository.

After setup, the first thing was to make a local repository on my machine(using “git init”) and cloned the remote repository to local repository.

“git pull” is used to fetch the data from the remote repository into local repository.

Here you can find some more important git commands.

Youtube tutorials for git
This tutorial series from “thenewboston” helped me a lot in learning git. In these tutorials, everything is explained clearly and in detail.

Web Development¶

Next, we needed to create a website for the documentation of our assignment. I don’t know too much about web development and fortunately this year in fabAcademy we have got ready made templates using markdown. So it was little easier for me to edit the default pages instead of creating a website from scratch. Still, I gave it a try of creating a wesite using HTML and CSS.

For that, I first installed the visual code text editor from here. One of the things you will find the most surprising, is that unlike other editors like sublime and all, VS Code does not come with a built-in web server. For installing the built in web server I chose to use the following procedure, which is quite simple yet powerful.

Steps
- Install Node.js from here

Create New folder for your project.
Add a package.json file to the project folder.
Install the web server by running command “npm install” in your terminal window.
Start the local web server by running “npm start”
Then, copy the local host address in your browser and start editing your files.

To create a new website from scratch for me was going to take a lot of time so I dropped the idea for now as I wanted to focus more on content and assignments. Website, I will try to develop over time. For now, we had mkdocs templates ready so I started to edit these.

MKdocs¶

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.
The thing which I liked about MKDocs is that we can preview our site as we write codes. Otherwise, it’s really difficult to work on for a newbie. Also, it reload and refresh the browser automatically.

I started with installing Python. You can download Python from here

After that, the next task was to install python package manager using “Python get-pip.py” in command prompt.

and then mkdocs “pip install mkdocs”

At that moment, I was all set to update my website on fabacademy.org

Next, I installed Visual Code Studio for editing the codes.

Publish website locally

Open command prompt. (Win+R-> type “cmd”->OK)
Head to your local repository(cd “name of the folder”) and run command “mkdocs serve”.
Copy the adress and paste it in the web browser.
Next, update the md files in text editor and refresh the web browser.

Useful Links¶

Tutorials¶

Learning Outcomes¶

I learned how to setup git for project documentation.
After getting used to of common commands of Git and Markdown, I started enjoying documentation and website creation.

You must tell yourself, ‘No matter how hard it is, or how hard it gets, I’m going to make it’- Les Brown

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.