1. State of the art, project management and documentation¶

Weekly Assignment

Learning Outcomes :

Research skills: Learn the process and tools used to document course work
Design & process skills: Acquire the necessary skills to publish projects, documentation and share the results of each assignment

Student Checklist :

Build a documentation website describing you and your motivation for the textile-academy, including your previous work
Upload the documentation to your project page on class.textile-academy.org
Add references and research based on the topic of your interest
Learn how to upload images, videos, references and how to use Markdown and Gitlab
Learn about the fab lab processes, booking system, usage, machine demos, tools and safety rules
Customize your website and document how you did it (extra credit)

References & Inspiration¶

There are several people whose webpages I look up to, for their technical detail, visual beauty, clarity of organization, or just overall inspiration.

At my own node, there is Shefali Desai whose documentation was quite celebrated last year.

Shefali also directed me to Rico's and Mina's pages for reference, that she had referred to.
Rico's Week 01 documentation is amazingly detailed yet clear. I agree with him saying that while we know of the importance of documentation from FabAcademy, the quality of documentation can be raised. All the work seen at Fabricademy so far raises that bar very high.
Mina's page uses this lovely softened font that I will try to steal ! I also liked her storytelling.

The template also pointed me to more people who I appreciated.
I liked Neyla Coronel's pages for the gradient in the top bar as well as her inspiration from nature.
Stephanie Vilayphiou has the amazing css-based background tiling that I want to try out, as well as some crazy typography.
The amazing graphic thumbnails from Barbara Rakovska are beyond me for now, but it's an inspiration to have some very cool graphics there.

I will keep adding more pages here as I find them ! I wander somewhere between

Art is never finished, only abandoned. (?Da Vinci)

and

Perfect is the enemy of good (?Voltaire)

Documentation¶

First off, let's understand why we document !

Judging the work : This is ofcourse necessary if the work is to be assessed for any reason.
Documentation as learning : Because doing the documentation reinforces one's learning, the process, and gives new insights
Portfolio : as a showcase of the work, process, thoughts, etc
Self re-learning : referring back to your work to understand what you had done in the past, your approaches, and missed pathways
Teaching : your work as a study used by you or others as a reference

Over the past few years, all of these purposes have come to pass, and my FabAcademy as well as other project documentations have come in handy when I needed them.

During my FabAcademy program, I was very new to setting up WebPages and putting content on them. I developed a workflow that worked for me then. Since then, I have set up multiple websites/pages though. As I have grown more confident of using Git and Gitlab, I have streamlined the workflow to eliminate maintaining multiple copies and other actions that were no longer necessary. Here is my current workflow.

Website Tools¶

Git
VSCode
VSCode Plugins :
- GitHub Pull Requests (Github)
- Live Server (Ritwick Dey)
- Duplicate action (mrmlnc)
- File Utils (Steffen Leistner)
- Markdown All In One (Yu Zhang)
Python
MKDocs
MKDocs plugins
- mkdocs-git-revision-date-localized-plugin 1.3.0
- mkdocs-glightbox 0.5.1
- mkdocs-material 9.5.49

Website Workflow¶

My website workflow is mainly writing the markdown text, linking images and files, etc in VSCode, with MKDocs installed, while checking the outcome in the browser using the mkdocs serve command. VSCode has a built-in markdown viewer but it needs to split the screen and I was happier with the server. I also have a second screen attached so it is easier to have one screen for VSCode and one for the browser render.

One can always edit using another text editor or gitlab's web editor as well.

GIT, VSCode, Python¶

I already had git, VSCode, Python and MKDocs installed, but they are easy enough to install. Just follow the instructions. Install the VSCode extensions as well.

Python is a prerequisite install for MKDocs, and when you install Python, make sure the "Add to Path" is checked.
Then install MKDocs : pip install mkdocs from the python terminal or from VSCode's Integrated Terminal
For the Material theme, pip install mkdocs-material should do it for you.
Install any other mkdocs plugins and themes you may want.
Check what you already have installed using pip list

Getting Started with MkDocs

Connecting to GitLab - The SSH Key¶

The first part of being able to communicate securely between the desktop and the Gitlab website is to have the SSH key generated and added to the right places.
Use SSH keys to communicate with GitLab is a good start. I had followed this and did not have any issues.

Useful sections :
Generate an SSH key pair
Add an SSH key to your GitLab Account

Cloning the Repo¶

From the Gitlab web page, copy the SSH clone URL.

At the VSCode Terminal,

navigate to the folder on my drive where I wanted my local copy to be created
use git clone <SSH URL> and replace the <> with your own URL

This will create a copy of the repository locally, and the VSCode GIT extension will keep an eye on it for changes, sync etc.

The repo will contain a few pre-built files and folders

mkdocs.yml : The YML file
This is the main instruction file for the website. Use this to edit the site name, the author name, urls, add and change colours, fonts, themes, and other visual aspects.
This file also controls the plugins and extensions that change how certain things behave or look.
The glightbox plugin creates a lightbox, i.e. a full screen popup display, for any image on the page, so you don't have to go back and forward or open new tabs.
The attr_list extension allows you to specify image sizes so you don't have to crop and resize each image file.
Readme.md :
This file contains the basic text that you see when you go to the GitLab repo homepage. You can ignore this for now, or use it to practice writing and editing markdown.
requirements.txt :
this file contains a list of plugins and extensions that the server needs to install to be able to run your mkdocs page and turn it into a webpage. It will contain entries similar to your pip list of your installed plugins, but usually specific to this one project rather than all your extensions in case you have more. The Python Requirements File
.gitlab-ci.yml : The pipeline action file
This file contains instructions for gitlab to execute to be able to transform your md files to html and deploy them as webpages. DO NOT EDIT.
docs folder, and subfolders : The Content The docs folder contains a series of subfolders, each containing what the name suggests - files, images, assignments etc. You will add more of your content to these folders.
- assignments folder : contains the weekXX.md files for 13 weeks of exercises
- development and project folders : for relevant pages of your project
- files folder : place to keep all code, stl, and other files, for each week and project
- images folder : for all the images, for each week and project
- stylesheets : extra css and js to modify your base Material theme colours, icons, etc
- index.md : The Landing Page for your Website !

Editing the Repo files¶

I edited the mkdocs.yml file to update my name, the site name, etc. I also played around with the colours and icons. I would like to add some more custom colours and gradients as well.

Then I edited the index.md file to write my entire text and left tags for where I wanted images.

The text was formatted using markdown notations.

Text formatting
- Bold
- Italic
- Inline Code
Links
Images

codeblocks()
{
    you.breathe(6000);
}

Open Sesame

    Expandable blocks.

I kept checking the rendered page in the browser using mkdocs serve which was running in the background.

The VSCode markdown preview shows slightly different renders as compared to the browser. Since the browser is rendering through MKDocs and the Material theme, and is identical to what the webpage will actually look like, in case of differences, go with the browser render. This is another reason I don't prefer to use the preview instead of the live server.

Admonitions¶

These are a feature of material-for-mkdocs. I haven't used them very extensivley yet, but they are coming rather handy for collapsible text boxes.

Syntax	Example	Icon	Default Color
`!!! note`	!!! note "Note"	🗒️ `note-outline`	Blue
`!!! abstract` / `!!! summary` / `!!! tldr`	!!! abstract "Summary"	📘 `book-open-outline`	Blue-gray
`!!! info`	!!! info "Info"	ℹ️ `information-outline`	Blue
`!!! tip` / `!!! hint` / `!!! important`	!!! tip "Tip"	💡 `lightbulb-on-outline`	Green
`!!! success` / `!!! check` / `!!! done`	!!! success "Success"	✅ `check-circle-outline`	Green
`!!! question` / `!!! help` / `!!! faq`	!!! question "Question"	❓ `help-circle-outline`	Teal
`!!! warning` / `!!! caution` / `!!! attention`	!!! warning "Warning"	⚠️ `alert-outline`	Amber
`!!! failure` / `!!! fail` / `!!! missing`	!!! failure "Failure"	❌ `close-circle-outline`	Red
`!!! danger` / `!!! error` / `!!! bug`	!!! danger "Danger"	☠️ `alert-octagon-outline`	Red
`!!! example`	!!! example "Example"	🧩 `code-tags`	Indigo
`!!! quote` / `!!! cite`	!!! quote "Quote"	💬 `format-quote-close`	Gray

note

abstract

summary

tldr

info

tip

hint

important

success

check

done

question

help

faq

warning

caution

attention

failure

fail

missing

danger

error

bug

example

quote

cite

todo

Adding captions in Markdown¶

Add the following to your extra.css file.
You can then use <small>This is my caption</small> to add captions underneath images within the markdown file.

    /* -------------------------------
    Image captions for MkDocs-Material
    ------------------------------- */

    /* Style <figcaption> inside figure */
    .md-typeset figure {
    display: inline-block;
    margin: 1em auto;
    text-align: center;
    }

    .md-typeset figcaption {
    font-size: 0.8em;
    color: var(--md-default-fg-color--light); /* matches MkDocs-Material gray */
    margin-top: 0.25em;
    text-align: center;
    line-height: 1.4;
    }

    /* Ensure images inside figures scale responsively */
    .md-typeset figure img {
    max-width: 100%;
    height: auto;
    border-radius: 4px;
    }

    /* Optional: style <small> captions used outside figure */
    .md-typeset p > small {
    display: block;
    text-align: center;
    font-size: 0.8em;
    color: var(--md-default-fg-color--light);
    margin-top: 0.25em;
    }

Markdown Resources¶

Markdown Guide - Basic Syntax for general formatting whenever I needed clarity.
Markdown Guide - Extended Syntax for creating tables and such-like.
Markdown Cheatsheet

Material for MKDocs reference

Admonitions in Material
How to Format Code in Markdown
Szymon Krajewski for 2 spaces = new line information
Daring Fireball's Markdown Syntax Page
Commonmark Markdown Tutorial
MkDocs Material Cheat sheet

Handy tip for image links¶

For quickly creating a list of links to image files,

export the images renamed as a sequence, for eg week01-01.jpg
copy the complete image link text into a spreadsheet and use it's drag-to-multiply functionality to generate more lines of links with a changing number, like the image below

Syncing the files¶

Once I was done editing, the Source Control Sidebar in VSCode showed me the changed files. I kept staging individual files since I wanted to commit them separately and keep the changes well organized, added the commit messages, and ran the sync-and-push command.

On the webpage, the little pie of doom appeared.

(I am not traumatised by it anymore, but back during Fab, I could not get the site to run for the first 6 weeks, and the pie and failed signs were very stressful)

Initially, there were a couple of issues, locally as well as online

glightbox was not installed, and that threw errors locally. I installed it from the terminal and it worked out fine.
mkdocs-git-revision-date-localized-plugin was a different version in the original requirements.txt so I updated the mkdocs.yml file locally, but then the online version threw errors until I updated the requirements.txt and synced it. In hindsight, I should have just updated the local version.

Changing the mkdocs.yml and requirements.txt files makes it take a longer time to run and deploy, but updates to the content itself are fairly fast to render and update.

Finally, the pies-of-doom were digested and the green-tick-of-relief came up !

My new landing page was ready-ish. I still had to add a lot of images and links.

Visual Design Directions¶

Once the basic setup of the website and dataflow is sorted, these are theing things I want to do for the website

better typography
more colours
background images or textures
coded visuals in the background

Documentation Tools and Workflow¶

To manage the vast volume of data and make sure everything is available and accessible, I use the following tools and workflow.

File Types¶

Most of the data can be distilled into the following types :

Images :

Photographs
- Cellphone
- Camera
Screenshots
Downloaded images
Other (Scans, Renders, etc)

"Technical" Files (CAD and Code) :

CAD files - f3d, stl, etc from their respective software
Vector files - svg, dxf, ai, cdr, etc from their respective software
.ino files for Arduino code
other code scripts (processing .pde, javascript .js. etc)
zip files of any group of files

Videos :

Screen recordings
Live action from cell/camera

Software and Apps¶

To manage or edit each type of data, I use the following utilities and software :

Screenshots and screen recording : ShareX
Photographs and Images - manage, resize, and basic edits : I prefer Lightroom, but Digikam, IrfanView, XnView are free alternatives
Image editing - I prefer Paint.net, it's light and powerful enough, though I have used GIMP in the past
Videos from individual frames - FFmpeg CLI
Videos edits - Handbrake
Bulk Rename Utility - for amazing batch file renaming power
Everything - easy windows file search instead of folder navigation
WinMerge - compare the contents of 2 or more files or folders to check for duplicates, changes, etc. Extremely useful to compare two folders, for eg, a fresh downloaded clone and a local clone of the repo, to check for differences.
WinDirStat - a graphical folder tree viewer to check file and folder sizes across the entire depth and breadth of your folder structure, to find large or forgotten files within your organisation
ChatGPT - quick code snippets for js, ino, ffmpeg or bat files
7zip for zip files
Ninite - useful when doing initial installations to a new machine to add a lot of these utilities in bulk

Apart from these general utilities,

CAD - Fusion 360, Rhino + Grasshopper are my usual go-tos
STL files - built in windows viewers, Meshmixer for minor edits
Vectors - Inkscape for it's amazing plugins and community, CorelDraw for comfort; I have a long history with CDraw since all commercial print, laser or cnc operator services use CDR files and not AI

Workflow¶

Folder Organisation¶

I created a Fabricademy folder on my machine, and created the following subfolders

Fabri_working : the working folder where all files and other data would land, unedited images, WIP code, etc
- _Photos_inbox
- _Downloads_inbox
- _Screenshots_inbox
- Week01, Week02, etc
The _inbox folders recieve the image dumps from my screenshots folder or when I transfer from cellphone or camera. The weekNN folders are to sort out the respective images and other files by their weekly exercise.
Fabri_docu
the folder where selected data and files would be placed to go to the repo - the subset of selected and exported images, resized and renamed, hero shots, clean code files, etc

Files and data flows between them as follows :

File dumps from the windows screenshot folder, cellphone/camera image transfers, and various other sources are brought to the Working folder that will collect all data related to Fabricademy.
The inboxes are sorted and files are sent to respective weekly folders.
The weekly folder is parsed and images are selected, edited and exported to the Docu folder. Other final files are also transferred to the Docu folder.
Files from the Docu folder are copied over to the local repo, to be used in the text, linked, and uploaded.

This separation allows two major things to happen :

The Docu folder will be massive and can be partially transferred off the local drive onto USB storage, etc, without affecting the main documentation content.
A larger dataset is available but out of the way if more photos, etc are needed to be added to the website or referred to for any reason
Maintains a copy of the unedited, unrenamed images vs the resized and edited smaller images.
Maintains a clean copy of the edited images as well as final files incase local repo is somehow overwritten or lost

Maintaining a raw copy of the complete dataset, a final copy of the selected dataset, and a local repo version of the selected dataset seems like overkill, but, as they say, "all safety rules are written in blood". This segregation saved my skin often when I was more prone to making mistakes. I will keep an eye on whether the middle copy is required or if I directly export to the local repo, but for now, this is my workflow.

Reflections¶

Since I come with a history of Fab as a participant and an instructor, it is interesting to reflect on my own workflows and how they have evolved over time.

Setting up most of the initial apps and tools was either not required since I already had them in place, or was very easy for me since I have done it often for my students or other websites. I had to access and edit the repo from my work laptop, and the cloning and syncing or adding plugins and extensions was not a challenge at all.
I am looking to level up my skillset, and since the basic setup is sorted, I am paying more attention to the extras. Colours, gradients, typography and the general visual look and feel casn go a notch higher than the basic defaults.
Writing the About Me page was also quite something - it was tough but I also enjoyed it. I am not someone who can talk about themselves very easily, so I have realised having these pages is a great way of letting people know who I am, what I do, and what I am interested in. Importantly, it is often a reminder to myself when I forget.
Collecting all the work showcased on the About Me page was also a reminder of how organised and how scattered all my material is. I have several places on the internet - some are my own websites, and some are platforms. Even after having these, there is a lot of work that exists only on my harddrive or the shelves of my studio. So writing the About Me is a great reminder to start pushing these.

And a recent quote I have come across

Share what you love, and the people who love the same things will find you. Austin Kleon, Show Your Work.

Credits¶

My thanks to my team and my instructors, as well as the Fabri team.
Shefali was amazing in reviewing these pages and giving me pointers on making the visuals pop ! Gunjan was missed but we'll see you next week !

And a shout out to Austin Kleon, I have re-read all three of his books in the past couple of months, and Show Your Work as well as Keep Going have both been a necessary read during a trying time.