My Environment

macOS again? How did I sink this low?

Let me figure out how to explain this… Better yet, I’ll explain it in a videoComing soon on Youtube or Instagram.

.

My keyboard is weird

While working on organizing Fab15 in Egypt, I noticed Sherry Lassiter typing at lightning speed without looking at the keyboard. At that time, I typed with two fingers and always looked at the keyboard. So, I decided to learn. There’s an advantage when you learn something from scratch – you have no bad habits. So, I didn’t learn the QWERTY system, which was originally designed to prevent old typewriters from jamming. I learned with the ColemakColemak is designed so that the most frequently used letters in the English language are on the middle row.

system. I have an ortho-linear keyboard with a Colemak layout, and I practice for about five minutes a day.

I also have a software on macOS that switches my keyboard layout to Colemak and also changes the function of the caps lock keyIn reality, I only used it to insult

to backspace.

My text editor is also weird

My intention is to use only vim, a command-line text editor. I have some knowledge of vim and I want to dive deeper into learning it. I like the idea of using only the keyboard to edit text. To avoid the temptation of using Visual Studio Code, I have uninstalled itJust kidding, I only removed the shortcut.

. The vim text editor is quite sparse by default. That’s why I have installed some plugins. Here is a list that I will expand over time:

• → NERDTree to have a sidebar with a file listing, so you can navigate quickly between files.
• → vim-devicons to visualize files and folders with a small graphic icon.

Other useful links:

• → VimAwesome is a website with hundreds of vim plugins
• → Fran’s My Computing repo with some tricks, in case you like using0.01% of the population
  
  the command line.

Reinventing the Wheel

I don’t have much free time. So, I need to come up with a system to write documentation quickly. As an unexpected benefit, this system allows you to have the documentation in two (or more) languages.

Using Markdown

I’m not exactly looking to break new ground here. The strategy that has served me well for many years is to write content in a plain text file in a format called Markdown .md. This way, I focus solely on writing the content. Advantages of writing in Markdown:

• You don’t need any special program to write plain text. You could even write it by hand if you have nice handwriting and scan it later.
• It’s easy to write, you don’t have to twist your fingers typing </h1> and stuff like that.
• It’s easy to apply styles and organize text.
• It can be read without feeling like you’re decoding The Matrix.

Fab Academy documentation must be presented in the form of a web page. There is a command-line program called Pandoc that literally converts any text format. I’m going to use it to convert .md files into nice-lookingNice-looking refers to being easy to read. Other people value the visual aspect of the page above all and prefer to spend time creating their own masterpiece. My best wishes to them.

.html pages with a CSS style template. The template has two advantages. On one hand, it allows me to forget about the visual aspect of the page. On the other hand, it makes it easy to add functionalities such as equations, tables, line numbers in the code, side notes, etc.

The template I’ve used is called Tufte CSS.Strongly inspired by the visual style of Edward R. Tufte’s books.

I modified the template because it wasn’t fully designed for multiple languages.

$if(toc)$
<nav id="$idprefix$TOC" role="doc-toc">
  $if(return-url)$
  <a href="$return-url$">$if(return-text)$$return-text$$else$← Return$endif$</a><br>
  $endif$
  <strong>Contents</strong><label for="contents">⊕</label>
  <input type="checkbox" id="contents">
  $table-of-contents$
</nav>
$endif$

On line 6, the word ‘Contents’ was hardcoded. Now, the word comes from the toc-title variable in the header:

$if(toc)$
<nav id="$idprefix$TOC" role="doc-toc">
  $if(return-url)$
  <a href="$return-url$">$if(return-text)$$return-text$$else$← Return$endif$</a><br>
  $endif$
  <strong>$if(toc-title)$
  $toc-title$
  $else$
  Contents
  $endif$</strong><label for="contents">⊕</label>
  <input type="checkbox" id="contents">
  $table-of-contents$
</nav>
$endif$

Saving time by dictating

Most of the text you’re reading, is being dictated in SpanishThe reason why I don’t dictate directly in English is that my accent is so bad that the computer can’t understand me.

inside a Markdown file. For dictating, I’m using macOS’s dictation tool.

I really like this tool because:

• It works everywhere in the operating system, including the terminal.
• It allows you to speak and take breaks of up to 30 seconds without disconnecting.
• You can edit the text while you are dictating.
• You can add emojis 😊
• It adds punctuation marks automatically, and you can also add them manually.
• You can also change lines and paragraphs using your voice.
• If your processor is Apple Silicon, it understands context and autocorrects. All this without a connection.
• I can use it while listening to music with my headphones.

Here is the complete list of voice commands in Spanish, English, and German. This saves me some time when writing. Some parts I have to write manually, for example, when I write code or include links. I also have to make some manual corrections.

File Structure

In the beginning, I used to write the text for each week in a single file. But as you’ll read later, I use a paid service for translation. Every time I edited a line, I had to translate the entire file again. To cut costs, I’ve divided the week into chaptersMy file structure is inspired by the programming language BASIC

and created a file for each chapter. That way, only the chapters I’ve modified get translated.

/documentation
    /es
        /md
            /w01
                w01-chapter-00.md
                w01-chapter-10.md
                w01-chapter-20.md
                w01-chapter-21.md
                ...
                w01-chapter-90.md

The file name encodes the week I’m in and the chapter. Chapter 00 is the header. I use chapters 10, 20, 30… to develop the sections of the week. If a chapter gets too long, I subdivide it using intermediate numbers: 20, 21, 22, etc. Chapter 90 is always the conclusion.

Later, I concatenateImportant Note: I never manually edit the concatenated file. I only edit the separate chapters.

all the chapters of the week into a single file, in this case, w01.md.

AI-Assisted Translations

At Fab Academy, documentation must be in English. Traditional language translators aren’t up to snuff. They fail to grasp the context and churn out results that sound funky. I’m bringing an artificial intelligence to the mix to translate the text of the chapters into English and also into German.

The AI model needs to get a grip on Markdown syntax and keep it intact. The model might get better (or even change) throughout Fab Academy. Hence, I’ll keep the Spanish text as is and rerun the translations on all files now and then. I’m only tweaking the files in Spanish. I won’t fiddle manually with the generated translations. So, if what you’re reading in English or German seems like gobbledygook, blame it on OpenAI or whatever model I’m rolling with.

I hit up César Garcia, from La Hora Maker, to scout for a model for this translation gig. César recommended the Whisper API from OpenAI, which can translate straight from Spanish audio. For now, I’m only after the translation, so I’ve set up an assistant in the OpenAI API with these instructionsI’ve got another model for German with similar instructions. I tweak the instructions now and then to try and improve the translations.

This file contains text with a mixture of markdown, yaml, pandoc and latex formatting. Translate the text from Spanish to English. Read the entire document to grasp context before translating it. Take into account nuances and idioms of the Spanish language and translate them to the equivalents in English. The translation should not be literal, focus on maintaining the original meaning and provide a translation that makes sense in english. Keep the formatting intact in the translated text, like footnotes, smallcaps, etc .Translate only the text within quotes in the YAML header of the Markdown file. Do not translate the latex notation, links, URLs, blocks of code and code snippets. If encountering a markdown link, only translate the text inside square brackets. Recognize and retain brands and names without translation. Use correct grammar and syntax in the final text. The style of the translation should be informal, with a touch of sarcastic humor.

Besides these general instructions, sometimes I need to pass a specific note to the translator. I’ve got a hack for adding special instructions in the markdown files. These comments show up in the markdown page, so the translator can read them. However, Pandoc ignores them, and they don’t appear on the web page. Brilliant, right?

[comment1]: <> (Note for the translator: Do not translate "hack" as it is universally used in all languages.)

After a fortnight of use, I can say the English translations are pretty darn good. Way better than what I’d muster, with a caveat: It seems that at times the system dumbs down. I’ve read other users griping about the same. It’s as if OpenAI can throttle or limit the resources allocated to the model. I got Sophia Döring to check out the German translation too. She reckons it’s generally on point, albeit occasionally it throws out some German words that are rarely usedThat might be triggered by how I pen the original text. I use Spanish equivalents of technical terms that, in everyday speech, I actually say in English.

, especially for technical terms.

This page you’re reading is about 4000 tokens long. You can figure out how many tokens a piece of text has using the OpenAI Tokenizer. Translating this page into both languages costs roughly 0.32 USD, considering each 1000 tokens cost 0.01 USD for input and 0.03 USD for output. The cost is manageable, given the quality. I’m signing up for this solution when I want to go global with my projects. At Fab Academy, I understand and brace for a considerable expense, given the multiple tweaks I’ll make on each page.

On my wishlist, I’m still scouting for a local model. That way, I can translate content more often without sweating the cost. I recently tested the Miqu-1-70b modelSupposedly leaked by an employee by accident. Miqu-1-70b might be a strong contender against GPT4

, with slow but satisfying outcomes. I see light at the end of the tunnel.

Automating Translation

Initially, I was using the OpenAI API window. Now, I’ve automated this process with a Python script. Using a mix of Bing Copilot and the free version of ChatGPT, I requested a program that could automate translation using OpenAI’s library. But it didn’t go well. After a lot of back-and-forth (AI doesn’t usually spit out correct code on the first try), I ended up losing my mind and hurling insults at Bing.

In the end, I had to read the API documentation to make the program work.

To avoid unnecessary extra costs, the script only translates the chapters in Spanish that I’ve added using git add. Thanks to this, I can control the costs better. Once this is done, I just run python translate-en.py, and the script generates the Markdown pages translated to English. I do the same for German.

Actually, I usually don’t do the translation in isolation, because I’ve included it in the next step.

All in one

Here’s how my process works: When I’m done editing the chapters, I run the following scriptIt’s a script originally written in Bash language that I created for the educational program FabZero and now I have converted to Python.

python auto.py --translate updating week 1

If the script finds --translate among the argumentsI do this to save costs, as I don’t want to translate the pages every time they are modified.

, it translates the modified chapters. Then it concatenates all the chapters and creates a single Markdown file for each week. The next step is to convert all those files into HTML. If, during the conversion, it finds a link to a Markdown document, it converts it into a link to its corresponding HTML document using this LUA filter. Finally, it uploads everything to Github provided there is a message, which in this case is updating week 1. If there is no message, it doesn’t perform any of the processes related to git.

You can analyze the script here: auto.py

Serving Web Pages

Let’s take a look at what I have on GitHub so far:

• My original .md files in Spanish
• The .md files translated into English and German by AI
• The .html pages generated by Pandoc for all .md files.

The only thing missing now is a web server. And you can set that up from GitHub by going to the repository’s CI/CD settings.

This will create a file in .github/workflows/static.yml, of which I only had to change the runner, because runs-on: ubuntu-latest wasn’t working. I changed it to runs-on: ubuntu-22.04 and upon committing, the pages were automatically served.

Final Result

https://thebeachlab.github.io/backtofabacademy2024/

Git: That Bottomless Pit

You might think that since I’ve been using git for 10 years I know everything there is to know about the version control system. Not at all. Here are the things I want to improve during this Fab Academy cycle:

• Curb my tendency to push changes to the main branch. Usually, it’s fine, but I need to get into the habit of creating a new branch for each change.
• Steal Get inspired by Neil’s aliases to run git commands more quickly.

(I might add more stuff throughout Fab Academy…)

Project Management

I’d like to dedicate a few lines to explain how I manage my projectsDon’t let anyone tell you how to manage a project. It’s something very personal and you have to create your own system.

. When you don’t have a boss, and nobody tells you what to do, you have to be very disciplined. Otherwise, you might fall into a negative spiral.

The most important thing is knowing where you’re going. Because if you don’t, you’ve got a serious problem. Sometimes you’ll find yourself lost in Fab Academy (and in your life). You don’t know what you want to do, you don’t feel like doing anything, and it seems like you’re moving in slow motion while the world races by. When that happens, remember Phil Stutz. Invest in yourself: Exercise, connect with others, write in a journal. It helps me and I’m convinced it will help you too. Soon, you’ll see your North Star. Head towards it.

Second is learning to reduce and simplify. One of your biggest problems in Fab Academy will be something like this: You can’t find a photo that you’re sure you had. You don’t know if it’s in your phone’s photos, on Google Drive, or on a USB drive, if you moved it to your computer’s folder, or if someone gave it to you on WhatsApp… Simplify. Reduce.

And lastly, and I think most importantly, the real secret to achieving anything, no matter how difficult, is by taking many, very small steps. You solve a small problem, then another, and then another. That’s how it works.

As for tools to help you manage, I’ve tried a few. So I’ll start with the ones that don’t work for me:

• Post-it notes on the wall. The idea is good. Very visual and quick. But it has two problems. First problem: In Barcelona, it’s usually very hot and the notes fall off. Second problem: If I can’t see the wall, there’s no project.
• Kanban-like software and similar. They try to mimic Post-it notes. I don’t use them because: I find them complicated and they don’t let me draw.
• Microsoft Project and the like. No comment.
• Web services like Notion.com, Monday.com, and similar. I’m not going to spend a second of my short life trying to understand how a service that only seems easy on TikTok (and will probably shut down tomorrow afternoon) works.

Now, I’m using a combination of plain text for long-term goals, reminders for medium-term goals, and Apple’s Freeform for the tasks I’m going to do today. Freeform is a program with an infinite canvas, similar to Miro. It has the advantages of Post-it notes without their drawbacks. I can customize it and create my own system. For example, I’ve created the DOING NOW box where only one note fits. For me, that’s important because I can only do one thing at a time. I can also draw by hand, and I like that. I’ll probably make a video explaining everything in more detail.

Final Project Sketch

Everything related to the final project has been shuffled off to its designated section.

Conclusion

At this moment, this entire system is making writing documentation slow and slightly tedious. But I believe that with this system, speed will dramatically increase week by week and eventually, I’ll be able to document things quickly and with great detail.

Moreover, I think this method is going to help many people who can’t express their talent because they’re not fluent in another language. It’s unfair for that to happen. I hope AI helps people demonstrate how valuable they are.