Documentation Week 1 - Project Management

Date: 11.10.2017 - 17.10.2017

In this first week we learn about designing website with HTML and CSS, and working with Git in order to produce documentation and safely make changes to the projects.

1. HTML & CSS Basics

1.1. Install the Brackets IDE

The IDE that Daniele introduced to us in the lecture is called Brackets (download link here). This IDE can be used to code in different languages, among which we use HTML and CSS for our website. It comes with many useful functions including syntax suggestion, syntax highlighting, autocomplete and so on.

1.2. Simple exercises

During the lecture we practised some basic HTML and CSS knowledge including

1.3. Building my website

Just with the basic knowledge it is already a good foundation for me to learn to build the basic frame of my website which consists of 4 parts:
  • a header with a background picture and a foreground picture,
  • a top navigation bar with 4 tabs "Home/Assignments/Final Project/About",
  • a content frame with the page's index menu on the left and the page content on the right,
  • and a footer with some information text.
Here are the examples of the codes I used inside the HTML body and in my CSS file for these parts:

Part of the website frame HTML Code CSS code
PAGE HEADER <div class="header"> <br><img src="../media/foreground_picture.png" height="30%" width="30%"> </div> .header { padding: 0px; text-align: center; color: lightseagreen; display: inline-block; background-image: url(../media/background_pic.png); background-size: cover }
TOP NAVIGATION BAR <div class="navtop"> <ul> <li><a href="../index.html">Home</a></li> <li><a href="#">Assignments</a></li> <li><a href="#">Final Project</a></li> <li><a href="about.html">About</a></li> </ul> </div> .navtop ul { list-style: none; background-color: cadetblue; text-align: right; padding: 0; margin: 0; } .navtop li { width: 150px; border-bottom: none; height: 50px; font-size: 1.2em; display: inline-block; margin-right: -4px; line-height: 50px; text-align: left; }
PAGE INDEX MENU AND PAGE CONTENT <div class="container"> <div class="row"> <div class="column left"> <h2 id="sideText"></h2> <div class="navside"> <h2 id="side_text">Page index</h2> <li><a href="#section1">1. HTML & CSS Basics</a></li> <li><a href="#section2">2. Using Git</a></li> <li><a href="#section3">3. Problems & Troubleshooting</a></li> </div> </div> <div class="column right"> Here goes the page content...</div> </div> </div> .row { margin-right:15px; margin-left:15px; } .column.left { width: 25%; list-style: none; } .navside { position: fixed; font-weight: 700; color: sandybrown; } .navside ul { width: 200px; float: left; } .column.right { width: 70%; margin-bottom: 25px; margin-left: 25px; }
FOOTER <div class="footer"> Thi Yen Thu Nguyen ● Fundamentals of Digital Fabrication 2017 ● FabLab Kamp-Lintfort </div> .footer { background-color: whitesmoke; font-weight: 700; padding: 5px; bottom: 0; text-align: center; position:fixed; width: 100% }

The CSS codes for the top navigation bar and the side menu are adapted from the snippets on this website.

2. Using Git

2.1. In the lecture

Git is a distributed version control system, which helps us to make backups and keep track of changes done to our projects. "Distributed" means that users clone the original repository from the remote server to their own machine, making distributed copies of the repo locally. Users then work and make changes on the local copies before they commit the changes to their local repo, and finally push the changes from local repo to the original repo on remote server.

We downloaded and installed Git (for Windows in my case). Here are some notes Daniele mentioned while running the installer:

We should select OpenSSH as the SSH executable,

and select "Use the Open SSL library" for HTTPS connections,

and select "Checkout as-is, commit as-is" for the line-ending conversions. This is because for now we only use a single computer or computers running same OS to work on the repo.

Next, we configured the email and user name, and then generated our own private and public SSH key

ssh-keygen -t rsa -C "your_email"

It is not necessary to give a new name of the SSH key file or give a passphrase. By default, the SSH keys will be saved under the folder C:/Users/Your-user-name/.ssh

2.2. After the lecture

The generated public SSH key has to added to the Gitlab account in order to push and pull data from local repository on remote server

  1. Log in to Gitlab using credentials received from the email and change the password
  2. Create a project and give it a name. For me I gave it the name FoDF_Documentation
  3. Go to Profile Settings, and then SSH Keys
  4. Copy the public SSH key from the file, which should be located in the folder C:/Users/Your-user-name/.ssh, and paste it to the field
  5. Enter a title for the key and press Add key to save it. Now go to the folder where we want to clone the repo and right click and then click on Git Bash Here:

  6. Then execute the commands to clone the repository to current working folder, line-by-line. For me the codes look like the following:

    cd path/to/desired/folder ###change working directory to desired folder, if we open Git Bash from anywhere else other than the desired parent directory git config --global "Thu Nguyen" ###username configuration git config --global "" ###email configuration git clone ###clone the repo from remote server to local machine cd FoDF_Documentation ###move to the sub-directory of the cloned local copy touch ###create the README markdown file git status ###check the status of the repo, modified and new files are shown in red git add ###add the README file to index tree git commit -m "add" ###commit the README file to HEAD tree with a message git push -u origin master ###push the changes in the repo to the remote server
    Here are the outputs of the Git Bash

3. Problems and troubleshooting

3.1. Problem signing the SSH key

Because I was using some other Git GUI application before, a private-public SSH key pair has already existed in the folder C:/Users/Your-user-name/.ssh, and thus the newly generated private-public SSH key pair are not saved in this folder but outside of the folder instead. As a result, after I copied my public key to the Gitlab repository and tried to push some changes to the repo, I encountered some problem:

The committed local changes could not be pushed because the SSH key pair is not put in the correct folder (at least for Windows). After I moved the SSH key pair to the folder C:/Users/Your-user-name/.ssh, everything worked fine again.

3.2. Problem with HTML & CSS

While trying to adding a footer to the bottom of my page, I keep getting the problem that the footer is not where it should be, like this:

By adding the following line to the footer class in my CSS file main.css, the problem was solved:

This means keeping the footer at a fixed position of the screen, no matter where the mouse is scrolling to. Knowing this, I use the same CSS property for my side bar navigation so that it is easy to keep track of the page's content from anywhere on the page.