Skip to content

State of the art, project management and documentation

Process

At the beginning of the week we were introduced to Markdown and the structure of our website. After some exploring to feel comfortable with how to edit it, I started thinking of the content and its structure.

Content: what do I want to add to my home page?

I looked for information about how to write an efficient "About me" page. I read a few articles, and gathered the ideas that resonated with me.

This is a summary of what I read:

  • Tell people what you stand for
  • Have your audience in mind, make it for them
  • Tell a story. Ask yourself what is the audience gaining from it. Does it demonstrate a claim you're making? Does it make a concept easier to understand? Will the reader learn something? Will they be inspired?
  • Suggest an action. For instance, reading other posts, following on social media or contacting you.
  • Add a picture of yourself (or a video!)
  • Make it in about 250 words.

With this information I wrote down a few basic points I wanted to address, and then read it out loud. I figured it was easier to talk about it than to write about it, so I recorded myself while elaborating these ideas talking out loud.

That's when I had the aha! moment: why not add recordings to tell my story? That way it is me speaking directly to the audience, which makes it more personal.

How to add audio files in GitLab Markdown

I couldn't find this in the documentation, so I googled a bit and found that adding HTML code pointing to the audio file works (source). 

<audio src="files/audios/intro_about_me.m4a" controls></audio>

Layout: how do I want to present the information?

After having a grasp on what I wanted to talk about and how, I started thinking how I wanted to make it look like. I work best if I just scribble stuff to get an idea and then polish the details. Enter my awesome wireframe sketch of the website:

Once I had this clear, I fiddled with Markdown and googled a lot to understand how to customize the Material theme in Gitlab. I ended up not changing it much, since to get to a different web design you need to hijack a lot. I may do so in the future, but for now I'm focusing more in the content. However, I cleaned up a bit the template by changing the font, removing the GitLab button on the top right corner, and playing around with the table of contents and tabs. My final mkdocs.yml looks as follows:

Click to show mkdocs.yml content
# Replace the text below to customize your site
site_name: Sara Alvarez
copyright: Copyright 2021 Sara Alvarez - Creative Commons Attribution Non-commercial

site_url: https://class.textile-academy.org/2021/sara.alvarez/
edit_uri: ""

extra:
social:
    # For other social icons at https://squidfunk.github.io/mkdocs-material/setup/adding-social-links/
    - icon: fontawesome/brands/instagram
    link: https://www.instagram.com/s.is.for.sara/

theme:
name: material
palette:
    # try other colors https://squidfunk.github.io/mkdocs-material/getting-started/#primary-colors
    primary: amber
    accent: amber
font:
    # See available fonts at https://fonts.google.com/
    text: Raleway
    code: Roboto Mono
icon:
    logo: material/fingerprint
features:
    - tabs

plugins:
- search

markdown_extensions:
- admonition
- codehilite:
    guess_lang: false
- toc:
    permalink: true

By the way, I found the Markdown extension Admonition really useful! It lets you insert collapsible blocks like the one above.

To avoid the issues with aligning and making a nice design for the page, I created a few picture collages and handwritten notes and drawings that I could insert as images. I also wanted to keep everything edited in a way that it felt personal, almost as if I was there telling my story and sharing pictures with the reader. That's why I kept the drawings and hand written annotations instead of changing them for more polished items.

The vision for my final project

This was a tough topic to address. I didn't (and still don't) have a clue of what my final project is going to be. So I asked myself something a bit more abstract: what kind of things do I like to make? And that question cristalized in the Venn diagram I placed on the page. I wanted it to represent the different drives that push me to making, and how when I combine all of them I really find joy.

From the presentation of the state of the art, especially the one from Anastasia in which she shared a bunch of links with inspiration, I found the work of Afroditi Psarra quite appealing. So that also gave me a hint of something I might be interested in for my final project.

Tools used

Sources