1.Principles and practices, Project management¶
This week I worked on defining my final project idea and getting used to the documentation process using GitLab and MkDocs.
Project managment¶
Summary¶
When I opened my GitLab repository, I saw the structure of my website. Before that, I didn’t have any experience with GitLab or website development, but I wanted to gain hands-on experience in building websites and using GitLab. I believe I can create a good website — I plan to use HTML and MkDocs with Python 3, and I’ll develop it in Visual Studio Code.
Tools¶
I use macOS as my operating system, and I’ve already gotten used to it — it’s very convenient for me to work on. I believe that all the software I use for Fab Academy can be easily installed and run on macOS.
VS Code
VS Code (Visual Studio Code) is a free and user-friendly code editor developed by Microsoft. It supports a wide range of programming languages, including Python, C++, JavaScript, HTML, and many others. VS Code features syntax highlighting, auto-completion, a built-in terminal, and numerous extensions, making it an ideal tool for both developers and students.
GIT
Git is a version control system that allows developers to track changes in their code, collaborate on projects as a team, and revert to previous versions of files when needed. With Git, it’s easy to store, manage, and update projects on platforms such as GitHub or GitLab. To document my weekly assignments and publish them on my website, I need to work with Git. I have already installed Git on my system.
Install git for macos¶
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install git
git --version
GIT command
I used the following Git commands. These are standard commands for working with a Git repository — for cloning a project and pushing updates after making changes to the website.
git clone <url> → copy (clone) an existing repository
git config --global user.name "Your Name" → set your Git username
git config --global user.email "you@example.com" → set your email
git status → show current changes, branch, and staged files
git add -A → add all modified files
git commit -m "message" → create a commit with a message
git push
PYTHON
Python is a simple yet powerful programming language used for developing websites, games, applications, artificial intelligence, and automation tools. It is easy to read and understand, making it suitable for both beginners and experienced professionals.
PIP
pip is a package manager for Python. It allows you to install, update, and uninstall external libraries and modules required for your projects.
I used the following pip commands while working with Python.¶
These are standard commands for installing, uninstalling, and managing packages, as well as installing all dependencies from a requirements.txt file.
pip install package_name # install a package
pip uninstall package_name # remove a package
pip show package_name # show info about a package
pip list # show all installed packages
pip freeze # list all packages (for requirements.txt)
pip install -r requirements.txt # install all packages from a file
MKDOCS
MkDocs is a powerful documentation tool that generates a website directly from your Markdown files. You simply write your content in .md files, and MkDocs automatically converts it into a clean, navigable website.
These are the commands I used to work with MkDocs — to install it and run my website locally.¶
First, I installed MkDocs:
pip install mkdocs # install MkDocs
This allowed me to build and serve static documentation websites.
Then, I installed the Material theme to improve the appearance of my site:
pip install mkdocs-material # install Material theme (optional)
I checked the installed version and available commands:
mkdocs --version
mkdocs -h
Next, I upgraded pip to ensure compatibility:
pip install --upgrade pip
I installed all required plugins, including the Git-based date localization plugin:
pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
I verified that the Python modules were installed correctly:
python -c "import material, mkdocs_git_revision_date_localized"
Finally, I launched a local development server to preview the site:
mkdocs serve
Markdown is a simple markup language used for text formatting. It allows you to easily create headings, lists, links, images, and tables without writing complex HTML code. Markdown is widely used in documentation, README files, and on platforms like GitHub.
Markdown examples
In my documentation, I used Markdown to add images, links, and headings. Here are a few examples I used:
# My First Heading
## My Second Heading
I can also add bold or italic text for emphasis.
I used the above syntax to insert images into my documentation pages.
[Visit Fab Academy website](https://fabacademy.org/)
I used this type of link to reference external resources and websites.
- Step 1: Design the schematic
- Step 2: Generate the board
- Step 3: Mill the PCB
I used bullet lists like this to describe steps in my process.
Using Markdown helped me keep my documentation simple, organized, and readable.
Create ssh key and Connecting a GitLab repository with my VS Code.¶
I thought it through and decided the best way to connect my repository in VS Code is via an SSH key. It’s password-free and hassle-free: add the key once, and after that you can git push without entering logins or tokens. It’s also safer than HTTPS + PAT, because your private key never leaves your machine (unlike a PAT, which is sent with every request).
Create ssh key
To connect to my GitLab repository securely without typing a password every time, I decided to use an SSH key.
Below is the full process I followed on macOS.
Generating the SSH Key
To connect to my GitLab repository securely without typing a password every time, I decided to use an SSH key.
Below is the full process I followed on macOS.
First, I used the following command to generate a new SSH key:
ssh-keygen -t ed25519 -C "yryszhan@example.com" -f ~/.ssh/id_ed25519
Next, I used these commands to start the ssh-agent and add my key:
eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
Copying the Public Key
After that, I copied the public part of my SSH key to add it to GitLab:
pbcopy < ~/.ssh/id_ed25519.pub
Adding the Key to GitLab
Then, I opened GitLab → Settings → SSH Keys, pasted the copied key, and clicked Add Key. Now GitLab trusts my computer.
Testing the Connection
To verify that everything works correctly, I used this command:
ssh -T git@gitlab.com
GitLab responded:
Welcome to GitLab, @yryszhan!
Clone the Repository¶
Next, go to the gitlab.fabcloud.org repository > copy Clone with SSH
After setting up the SSH connection, I cloned my project from GitLab using:
git clone git@gitlab.fabcloud.org:your-repository.git
Running site locally¶
MkDocs is a static site generator for Python that takes Markdown (.md) files and builds a website in HTML/CSS/JS—great for project documentation. I’m using MkDocs because it’s a simple, lightweight solution. I had no prior experience building websites, so I installed it on my machine with Python, and I’m running it with Python 3.10.
I tried running my site locally with MkDocs—it’s very convenient. As soon as I write or edit a page, I can see the result immediately.
mkdocs serve
I launched my website locally inside VS Code using the terminal.
The website was launched locally in the terminal, and a link appeared. When I clicked the link, the site opened in the browser.
My first commit¶
I added mkdocs.yml to the project root, then made my first commit and push. After that, I verified the config, updated my Markdown pages, and confirmed the site builds correctly with MkDocs locally.
Created a section about yourself on that website¶
I added an “About Me” page to the site where I wrote about my background and interests, and I also included a photo. Along the way, I learned how to write pages in Markdown and embed images. It was an interesting challenge and a great learning experience. I’ll keep improving the site.
List of resources¶
Use the Google search bar on the course directory page
A previous student's Mkdocs process
Using Artificial intelligence (AI)¶
I use ChatGPT to help me translate and write my texts in English in a more formal and professional way. Since my English level is still improving, it’s sometimes difficult for me to express all my ideas clearly and correctly on my own.
ChatGPT helps me not only with translation but also with structuring my thoughts, improving grammar, and polishing the language so that my writing sounds natural and academic.
In addition, I often use ChatGPT as a smart search assistant instead of a regular browser. The main difference is that with ChatGPT, I can instantly get accurate and summarized information without spending hours browsing multiple websites.
This approach saves me a lot of time and helps me focus more on learning, experimenting, and developing my engineering projects, rather than getting lost in endless internet searches.
Conclusion¶
This week was a great starting point for my Fab Academy journey. I learned how to organize my work, document my progress, and manage my project repository using GitLab and MkDocs. Even though it was my first time working with these tools, I quickly understood how they function and how useful they are for version control and documentation.
I also installed and configured Git, Python, and MkDocs, generated my SSH key, and successfully connected my GitLab repository to VS Code. Running my website locally for the first time and seeing it open in the browser was a very exciting moment — it made me realize that I can fully manage and customize my own site.
During the process, I faced a few issues. When I tried to upload a video file to my repository, I encountered the following error: remote: error: File
Throughout the week, I learned not only about technical tools but also about project management, documentation structure, and workflow discipline. Using ChatGPT as my assistant helped me write my texts more professionally in English and find information much faster.
Overall, this week gave me a strong foundation in project management, version control, and documentation — essential skills for all future Fab Academy assignments.