Week 01. Assignment 1. Principles and practices

Goal

The goal of this assignment is to build a site describing you and your final project. Fab Academy is about Learning, Making and Sharing, so documentation is key to achieve the diploma. The idea is to document all the progress every week, and then push it to the server (in our case, this year we are pushing the Archive to the Barcelona Supernode, and they will push it to the MIT server). Deadline for pushing to the Barcelona server is Tuesday at midnight Barcelona local time. Failure to do so will mean you won't be able to hand in on time, because your work will be offline in the MIT server.

HTML

At the beginning I was going to run a local copy of a WordPress Site with MAMP, and export the site to plain HTML using a plugin. There were a few reasons why I wanted to take this approach:

I am used to WordPress.
I wanted the documentation to be easy to read, and there are a lot of themes for this purpose.
During the Fab Academy I wanted to focus in content, not in coding HTML.
I could use some useful plugins to better document my work, like LaTeX plugins to show mathematical formulas and color coding for better reading code.

But there were a couple -let me say tiny- problems that forced me to switch back to raw HTML. The first one was related to links. The links must be relative to your folder, in my case /sanchez.francisco/. But Wordpress does not accept relative links. It thinks that your blog will be in one server and when you move it to another server you will just change one tag and it will be working again. It is not designed to export to static HTML that moves to other servers in the future. Also, if you ignore this advice and you keep linking to a specific server, when your instrutor will grade your work, they will remember you, but trust me, this is not the way you want them to remember you. The second one was uploading to the archive. Every time I export the Wordpress site to Static HTML, the whole site is exported with the current date, and when I use mercurial to push the changes to the Archive, it uploads all the files including images even I have only changed a single character in one of the pages. Now it is maybe OK because the site is only 1 mb. But I am not in the mood of uploading the whole site every time I change something during the Fab Academy.

Coding in raw HTML has other advantages over those fancy WYSIWYG tools. It helps you to structure your work and your mind. You miss a tag, or forget to close one, and something will not work as expected. Just like when you will be coding later in the Academy. Also you have full control of your site, with the other tools you are limited, those tools may let you change between lanes, but definitely you can not go off-road. And Fab Academy is also about going off-road. Lastly, you will learn HTML. So you wanted anyway!

So what I finally did is export the site to static HTML and then clean the HTML code to remove all the unnecessary lines related to Wordpress and fixing the broken links. I did it because I liked the Wordpress Meola theme from Elma Studio. But I do not recommend you to follow my steps. It has been very time consuming cleaning and fixing the HTML code. If I was born again what I would probably do is to pick a nice HTML template and start from there. A nice source of responsive templates is the Foundation framework.

At the end of the semester I added Prism to this site which is a syntax highlighter to display code in a nice way like this:


          # this is a nice way to show code

RECOMMENDATION: You know a very cool tool to make websites? Trash it. Learn some HTML, grab a text editor and code your web. Believe me, it will help you later in the Academy.

Mercurial

OK, the second day I was using Mercurial I thought: "What the hell is that? We are supposed to be doing this high-tech research and not only they recommend me to code in raw HTML but we are also using this sort of... what is that? a VT-100? like in the early 80's?". Now I feel more comfortable using the Terminal, I would say that it is even cool, I feel like in the movie "War Games".

MERCURIAL WORKFLOW: Once you have followed the initial configuration steps, which may differ from lab to lab, your should follow this workflow every time you want to sync the archive:

 hg pull

              hg update

              hg addremove

              hg commit -m "Describe here the changes you made"

              hg push

If you ever see something about "force push", just cancel. Wait a little bit and start over from the beginning.

IGNORING UNNEEDED FILES: You can ignore some files that you do not want to be pushed to the repository. For example, Mac OS users introduce extra unneeded files into the archive that don't need to be there. The most common of those is ".DS_Store". If you enter the following in a file named .hgignore, you can avoid this:
.DS_Store
.hgignore must remain in the top folder of the repository, next to .hg folder. It is not meant for personal ignores but for project-wide ignores (i.e. applying for everyone). If you want to ignore something others probably do NOT want to ignore, put it in your personal ignore in ~/.hgrc.

CONCLUSSION: 80's are cool. Most of the things I love belong to this decade. Why should someone resist something he loves?

What I learned

Sometimes the tools you like or you are used to, aren't the most suitable for a specific need. When learning, it is key to be open-minded, and accept those tools that at the beginning are unknown and uncomfortable.