Skip to content

Principles and Practices, and Project Management

Introduction

As part of my Fab Academy journey, I needed to set up Git and GitLab for managing my project files and documentation. Git is a powerful version control system that allows tracking of changes, collaboration, and efficient file management. This documentation provides a step-by-step guide on installing, configuring, and using Git on Windows, along with some mistakes I encountered and how I fixed them.

Why Documentation?

Neil pointed out some key reasons why documentation is so important. Here’s what stuck with me:

-Tracking Progress: Helps measure what’s working and what’s not.

-Learning Reinforcement: Writing things down helps solidify concepts.

-Portfolio Building: A showcase of your work, thoughts, and process.

-Self-Reference: Super useful when revisiting old projects.

-Teaching Others: Good documentation can help others avoid the same mistakes.

With these points in mind, I refined my documentation workflow to be as smooth as possible.

Installing Git on Windows

Git installation is the first step to managing my Fab Academy documentation effectively.

1. Downloading Git

-I visited the official Git website: https://git-scm.com/ Image -Clicked on Download for Windows. The website automatically detects my operating system and suggests the correct version. Image

-Once downloaded, I ran the Git installer (.exe file).

2. Installing Git - Step-by-Step

  1. Launching the Git Installer: -I double-clicked on the downloaded file (Git-2.x.x-64-bit.exe). -Windows asked for permission to run the installer – I clicked Yes.

  2. Choosing Installation Preferences: -Destination Location: I kept the default location: makefile C:\Program Files\Git

Image

-Selecting Components: I left all default options checked. Ensured that "Git Bash Here" was selected (this allows me to open Git Bash in any folder).

  1. Choosing Default Editor: Git asks which editor should be used by default.

I selected Vim (default), but Notepad++ or VS Code can also be used.

  1. Adjusting the PATH Environment Variable:

-I selected "Git from the command line and also from 3rd-party software" to ensure Git works in both Git Bash and Windows CMD.

  1. Choosing HTTPS Transport Backend:

-I chose the default option: Use the OpenSSL library.

  1. Configuring Line Ending Conversions:

-I selected Checkout Windows-style, commit Unix-style line endings (recommended). Image

  1. Extra Options:

-I kept default options checked, including Enable Credential Manager for Git credentials.

  1. Installing:

-I clicked Install and waited for the process to complete. -After installation, I clicked Finish and launched Git Bash.

Verifying Git Installation

After installation, I checked if Git was installed correctly:

1.Opened Git Bash (Right-click inside a folder → Select "Git Bash Here").

2.Typed the following command: git --version

3.Git returned the version number: nginx git version 2.x.x If Git doesn’t return a version, I probably made a mistake during installation. Reinstalling Git fixed this issue for me.

Configuring Git

After installing Git, I needed to configure my identity so that my commits have my name and email.

  1. Setting User Name: git config --global user.name "Your Name"

  2. Setting Email Address: git config --global user.email "your.email@example.com"

  3. Setting Email Address: git config --global user.email "your.email@example.com" Image

Generating SSH Keys for Secure Authentication

Since GitLab uses SSH keys for authentication, I generated an SSH key and added it to my GitLab account.

Image

1.Generating SSH Key Pair

  1. In Git Bash, I typed: bash ssh-keygen -t rsa -b 4096 -C "your.email@example.com"
  2. When prompted to "Enter file in which to save the key", I pressed Enter to use the default location.
  3. It then asked for a passphrase (optional but recommended).

2.Adding SSH Key to SSH Agent

  1. Started the SSH agent: eval "$(ssh-agent -s)"
  2. Added my SSH key: ssh-add ~/.ssh/id_rsa Image

3.Adding SSH Key to GitLab

  1. Copied the SSH Key: cat ~/.ssh/id_rsa.pub
  2. Opened GitLab → Settings → SSH Keys.
  3. Pasted the SSH Key and clicked Add key.

Cloning My GitLab Repository

Now that Git and SSH were set up, I cloned my Fab Academy GitLab repository.

  1. Navigated to my preferred folder: cd Documents/FabAcademy

  2. Cloned the repository: git clone git@gitlab.fabcloud.org:academany/2025/labs/[your-lab-name]/students/[your-username].git

  3. Navigated into the cloned folder: cd [your-username]

  4. Listed the files to confirm successful cloning: ls Image

Pushing My First Commit to GitLab

  1. Created a new file: touch README.md echo "My first Git commit" > README.md

  2. Staged the changes: git add .

  3. Committed the changes: git commit -m "Initial commit"

  4. Pushed the changes to GitLab: git push origin main

Conclusion

✅ Installed Git and verified installation.

✅ Configured user identity.

✅ Generated and added SSH keys.

✅ Cloned my GitLab repository.

✅ Pushed my first commit successfully.

This setup ensures smooth documentation throughout the Fab Academy!

Installing Python and Pip on Windows

Step 1: Download & Install Python

Go to Python’s official site and click "Download Python [latest version]" (it auto-detects Windows).

Run the Installer (.exe file) and check the box for "Add Python to PATH" (very important!).

Click Install Now and wait for the setup to finish.

Step 2: Verify Python Installation

Open Command Prompt (CMD) and type: python --version

It should display the installed Python version.

Step 3: Install pip (If Not Installed) Image

Python comes with pip by default, but to confirm, run: pip --version

If it shows an error, install pip manually:

python -m ensurepip --default-pip python -m pip install --upgrade pip

Step 4: Test pip by Installing a Package To confirm pip is working, install a test package

'pip install requests'

If no errors appear, Python and pip are set up correctly!

Common Mistakes I Made (And Fixed!)

Python Not Recognized? I forgot to check "Add Python to PATH" during installation. Fixed by reinstalling Python or manually adding it to System Variables.

Pip Command Not Found? Running it and upgrading software.

MkDocs

  1. First, I opened Command Prompt (CMD) by searching for cmd in the Windows Start menu.

  2. To install MkDocs, I ran:'pip install mkdocs'

The installation took a few moments, and I waited until I saw "Successfully installed mkdocs" before proceeding.

  1. To check if MkDocs was installed correctly, it displayed something like mkdocs, version X.X.X, that meant everything was good.

  2. Next, I needed to create a new documentation project. I navigated to the folder where I wanted to store my work. In my case, I used the Documents folder and added 'main address'.

  3. I created a new MkDocs project by running:'mkdocs new my-website', This automatically generated a folder named my-website, containing all the essential files for MkDocs.

  4. I then moved into my project folder: 'cd/ e my-website'

  5. To check if everything was working properly, I started the MkDocs server by running: 'mkdocs serve' This launched a local development server, and it showed a link like http://127.0.0.1:8000/. Image

  6. I copied that link and pasted it into my browser, and the default MkDocs site loaded successfully!

  7. To edit my site, I opened the mkdocs.yml file in a text editor (VS Code in my case) and modified the settings like the site name, theme, and navigation structure.

  8. I also customized the content inside the docs folder by adding Markdown (.md) files for different sections of my documentation. Image

After making edits, I restarted the MkDocs server with mkdocs serve to see the changes live in my browser.

  1. Finally, I wanted to publish my MkDocs site online. Since I was using GitHub Pages, I simply ran: 'mkdocs gh-deploy' Image

This automatically uploaded my site to GitHub, making it accessible to anyone.

Mistakes I Made (And How I Fixed Them)

Problem: The mkdocs command wasn’t recognized.

Fix: I had forgotten to add Python to the system PATH during installation. Reinstalling Python and ensuring "Add Python to PATH" was checked solved it.

Problem: The MkDocs server wouldn’t start.

Fix: I realized I had modified mkdocs.yml incorrectly. Checking the syntax and fixing indentation errors resolved the issue.

Problem: My site wasn’t updating even after running mkdocs serve.

Fix: I needed to clear the browser cache or restart the server for changes to take effect.