1. State of the art, project management and documentation

Introduction

The first week of Fabricademy focused on the importance of documentation and project management within the context of digital fabrication and open-source knowledge sharing. Clear and consistent documentation allows us to track our progress, reflect on our process, and make our work accessible and replicable for others around the world.

We were introduced to the main tools and workflows used throughout the course to maintain our personal documentation websites. This included using Git for version control, GitLab as the remote repository platform, and Visual Studio Code as a text editor for writing and updating our content.

In addition, we learned the basics of Markdown, a simple formatting language used to create structured and readable content for the web, and MkDocs, the static site generator that powers our documentation pages.

Since I had previously completed the Fab Academy program, I was already familiar with all of these tools and workflows. This allowed me to quickly set up my environment and focus on refining my documentation structure and workflow from the start.

This week served as a foundation for building a reliable documentation system, which will be essential for tracking and sharing my work during the rest of the program.

Understanding Git and Version Control

What is Git?

Git is a distributed version control system used to track changes in files, manage project history, and support collaboration across teams or individuals. It was originally developed to help software developers coordinate their work, but its flexibility has made it useful for a wide range of applications, including documentation and digital fabrication projects like those in Fabricademy.

When working on a project, Git allows you to make “commits,” which are saved versions of your work. Each commit contains a snapshot of the project at a particular moment, along with a message describing the changes made. This makes it easy to go back to earlier versions, compare changes over time, and experiment safely without losing progress.

Another important feature of Git is branching. You can create branches to test new ideas or make major changes, and later merge them back into the main branch once they’re ready. This system encourages experimentation while maintaining a stable version of your work.

Overall, Git helps organize your workflow, reduce mistakes, and ensure that every step of your project is documented and reversible.

Working with GitLab

While Git works locally on your computer, a platform like GitLab hosts your project repository online. Think of GitLab as the cloud-based interface where your work is stored, backed up, and made accessible to others (including instructors and collaborators).

Each Fabricademy student is provided with a personal GitLab repository. This repository is where all your documentation, images, and project files are stored. By syncing your local files with your GitLab repository, you ensure that your work is visible on your online Fabricademy documentation site.

The basic workflow looks like this:
1. You clone your repository from GitLab to your local device (this creates a local copy).
2. You edit and update your files locally (e.g., writing markdown documentation or adding images).
3. You use Git to commit your changes with a descriptive message.
4. You push your changes to GitLab, updating your online repository and website.

Later in the week, we explored this process in more detail using Git Bash or a terminal, as well as Visual Studio Code. Together, Git and GitLab form the foundation of your version-controlled documentation system for Fabricademy.

Installing Git and Cloning the Repository

Installing Git

To begin working with Git and GitLab, the first step is to install Git on your local computer. Git allows you to clone your Fabricademy repository, track changes locally, and push updates to your online documentation.

Steps to Install Git:

1. Go to the official Git website: https://git-scm.com.
2. Download the version that matches your operating system (Windows, macOS, or Linux).
3. Run the installer and follow the default installation settings. On Windows, this will also install a command-line interface called Git Bash.

4. After installation, open a terminal (or Git Bash on Windows) and type the following command to verify the installation:

   --git --version

If Git was installed successfully, this will return the installed version number.

Cloning Your Fabricademy Repository

Each student is provided with a personal GitLab repository for their documentation. Cloning this repository creates a local copy of your website on your computer, which you can edit and update before pushing changes back to GitLab.

Steps to Clone Your Repository:

1. Log in to your Fabricademy GitLab account.
2. Navigate to your personal repository (provided by your instructor).
3. Click the Clone button and copy the HTTPS link.

4. Open your terminal (or Git Bash), navigate to the directory where you want to store your project, and run the following command:

   --git clone https://gitlab.fabcloud.org/your-username/your-repo-name.git

5. Once the cloning is complete, a new folder will appear in your directory containing all the files and folders from your GitLab repository.

Folder Structure Overview

Inside the cloned folder, you will find:
- A docs/ folder — where all your markdown documentation will go
- An images/ folder — for storing images used in your pages
- The mkdocs.yml file — which controls the navigation and structure of your site

You can now begin editing your content locally.

Basic Git Commands

After editing your documentation, you will use Git to stage, commit, and push your changes to GitLab. Here are the basic commands you’ll use:

Navigating with Git Bash or Terminal

Use these commands to move between folders and view contents:
- cd folder-name – change directory
- cd .. – go up one level
- ls – list folder contents (or dir on Windows)

Committing and Pushing Changes

Once you’ve made changes to your files:

1. Stage all modified files:

   --git add .

This prepares your changes to be committed.

1. Commit the changes with a message:

   --git commit -m "Added week 1 documentation"

Commit messages should be clear and concise.

1. Push the changes to GitLab:

   --git push

This updates your online repository and your documentation website.

You can also check the current status of your repository using:

 --git status

This will show you which files have been changed, which are staged, and whether your branch is up to date with the remote repository.

By following these steps, you establish a workflow where you can edit your documentation locally, track your progress, and safely publish updates to your online portfolio.

Setting Up Visual Studio Code (VS Code)

Installing VS Code

Visual Studio Code (VS Code) is a lightweight but powerful code editor developed by Microsoft. It supports a wide range of programming and markup languages, including Markdown, and is well-suited for editing your Fabricademy documentation.

Steps to Install VS Code:

1. Go to the official website: https://code.visualstudio.com
2. Download the version for your operating system (Windows, macOS, or Linux).
3. Follow the installation steps provided by the installer.
4. Once installed, launch VS Code.

Recommended Extensions

Although not required, the following extensions can enhance your experience when working with Git and Markdown:
- GitLens – provides a visual interface for Git inside VS Code.
- Markdown All in One – helps with Markdown formatting and previewing.
- Live Preview – allows you to preview HTML and Markdown output in real time.

You can install extensions by clicking the Extensions icon on the sidebar or pressing Ctrl+Shift+X, then searching for the extension by name.

---

Opening Your Local Repository in VS Code

After cloning your Fabricademy repository, you can open it in VS Code to begin editing your documentation files.

Steps to Open the Folder:

1. Open VS Code.
2. Click on File > Open Folder...
3. Navigate to the folder where you cloned your repository.
4. Select the folder and click Open.

You will now see your repository’s contents in the left-hand file explorer.

Important Folders and Files:

• docs/ — This is where you’ll place your weekly documentation, typically as Markdown files (.md).
• images/ — Use this folder to organize and store the images used in your documentation.
• mkdocs.yml — This configuration file defines your website structure, sidebar navigation, and metadata.

---

Editing and Updating Documentation

Editing Markdown Files:

1. In the file explorer, go to the docs/ folder and locate the Markdown file you want to edit (e.g., week01.md).
2. Click to open the file. You can now begin writing or updating your documentation using Markdown syntax.
3. Save your changes regularly by pressing Ctrl+S (or Cmd+S on macOS).

Previewing Markdown:

To preview Markdown files:
- Right-click on the open Markdown file tab and select "Open Preview".
- You can also split the screen to view both the raw Markdown and the rendered version side by side by clicking the small preview icon in the top-right corner of the tab.

Some extensions also allow live previewing and formatting suggestions as you write.

Once your edits are complete, you can return to your terminal or Git Bash to add, commit, and push the changes using Git. This workflow allows you to maintain and update your online documentation site in a clean and organized way.

Writing in Markdown

What is Markdown?

Markdown is a lightweight markup language used to format text for the web in a readable and structured way. It allows you to write clean documentation using plain text, which is then converted into a visually formatted website.

Markdown is widely used because it’s easy to learn and doesn’t require any special software to write or read. In Fabricademy, we use Markdown to write and organize our weekly assignments, which are then compiled into a static website using a tool called MkDocs.

This system provides a clean and efficient way to write, format, and publish your work consistently across all weeks of the program.

---

Basic Markdown Syntax

Below are the most commonly used Markdown elements you'll need when documenting your work:

Headings

Use # symbols to create headings. More # symbols mean smaller headings.

# Heading 1
## Heading 2
### Heading 3

Bold and Italic Text

Use asterisks or underscores to format text.

**bold text**
*italic text*

Lists

Use dashes - or numbers followed by a period 1. to create lists.

Unordered list:

- Item one
- Item two
- Item three

Ordered list:

1. First item
2. Second item
3. Third item

Links

Use square brackets for the link text, followed by parentheses for the URL.

[Visit Fabricademy website](https://textile-academy.org)

Images

Use the same format as links, but add an exclamation mark ! in front.

![Alt text](../images/week01/image1.jpg)

Inline Code

Use backticks to format short pieces of code or commands inline:

Use the `git status` command to check your repository.

Code Blocks

Use triple backticks to display larger blocks of code:

git add .
git commit -m "Updated week 1"
git push

---

Using Markdown allows you to keep your documentation clean, consistent, and compatible with static site generators like MkDocs. It’s a valuable skill not only for Fabricademy but also for any future technical or collaborative projects you may work on.

The MkDocs Template and YAML File

Structure of the Fabricademy Website

Fabricademy uses a static site generator called MkDocs to build and maintain each student’s personal documentation website. MkDocs takes the content written in Markdown files (.md) and automatically generates a well-structured, navigable website.

When you clone your Fabricademy repository, you'll find a default folder structure that includes:

• docs/ — the main directory containing your documentation.
• Subfolders inside docs/ for each week (e.g., week01, week02, etc.).
• A mkdocs.yml file — the main configuration file that defines how your site is built.

This setup allows you to focus on writing and organizing your weekly assignments without needing to manage any web code. The website is automatically rebuilt each time you push changes to GitLab.

---

Understanding the mkdocs.yml File

The mkdocs.yml file, located at the root of your repository, defines key information about your documentation site including the title, author, theme, plugins, and more.

Here is a simplified breakdown of the main elements:

• site_name: Appears at the top of your site.

• site_description: Optional text that describes your site.

• repo_url: Adds a link to your GitLab repository in the top-right corner.

• theme: Controls the appearance of your site using the Material for MkDocs theme.

Conclusion

Week 1 provided a solid foundation for the rest of the Fabricademy journey. By setting up our documentation tools and understanding the basics of version control, we established a workflow that supports both creativity and technical organization.

Through Git and GitLab, we gained control over how our work is saved, shared, and managed. Using Visual Studio Code made it easier to edit and structure our content, while Markdown and MkDocs offered a flexible way to format and present our documentation clearly.

Having previous experience with these tools from Fab Academy allowed me to move through the setup process efficiently, but revisiting the fundamentals helped reinforce best practices and refine my workflow.

This week emphasized that documentation is not just a requirement — it is a powerful tool for reflection, collaboration, and open knowledge sharing. As the course progresses, this system will grow into a complete portfolio of experiments, challenges, and discoveries.

1. Install Git: I downloaded and installed Git on my local machine from the official Git website.

   

2. Clone Repository Locally: I began by cloning the remote repository to my local machine using the git clone command. This creates a local copy of the repository on my computer. The link to clone the repository was obtained from my GitLab website, where the project repository is hosted. I copied the clone with HTTPS link from the code tab.

 ```

 git clone <repository_URL>

 ```

1. Configure Git: I set up my Git configuration with your username and email address using the git config command.

   git config --global user.name "Your Name"
   
   git config --global user.email "your_email@example.com"