Markdown for Readme’s

It seems a lot of people crank about writing documentation, so I wasn’t looking forward to writing some for Wikiwhat, but I knew it was important, not just to for the sake of doing it, but because as the n00biest of n00bs, I wanted someone with no idea of how things work to be able to use our gem easily, on the off chance anyone would want to use it. However, it turned out that writing the documentation for Wikiwhat was way easier than writing lab reports or manuscripts, and I had a lot of fun doing it.

If you have never used markdown before, this page is a good summary of the basics of markdown syntax.

Use Mou

Mou is a great Markdown editor that shows you what you markdown will look like as you are writing it. I found this really helpful as I was experimenting with the different formatting options in Markdown. It can also do a bunch of other fancy things. The one catch is that it does not currently support Github-flavored Markdown, so Github-specific Markdown will not be rendered correctly. To check anything Github-specific, you will have to check out one of the Github-flavored markdown previewers.

Make Internal Links

This one tripped me up for a while, but it’s secretly really easy.


gives a link to google like so:


But I wanted to make links within a page, so someone reading the README could jump to the section they wanted to read without scrolling though the whole page. Github makes this easy by turning any header into an internal anchor point!


will make a link to the ‘Usage’ header lower down on the page. If the header text is more than one word, the text is converted to all lowercase with dashes (-) replacing the spaces, like so:

[A Header With Multiple Words](#a-header-with-multiple-words)

Specify the language

You will probably want to have code examples in your README. Github will syntax-highlight them for you correctly if you tell it what language it is. When you make a code fence, specify the language immediately after the first ‘fence’ for correct syntax hilighting.

<ruby code>

Ruby Gem: Wikiwhat. It’s alive!

We did it! One functional Ruby gem, made!

If you didn’t come to career day, you can check out our presentation (above) or our github repo: Wikiwhat. You can find Bonnie, my partner in crime on this endeavor @BonMatts on Twitter.

Of course, there are a lot of bits and pieces to still work on, and we have a ton of features we’d like to add, but I’m pretty happy with how well it turned out.

And hey! Jimmy Wales retweeted us! That was pretty cool. :D

Writing a Ruby gem!

For my final project, I’m working with Bonnie Mattson on a Ruby gem, currently called ‘Wikiwhat’, for the Wikipedia API! This is a really fun project, and also really challenging. The last few weeks of class have focused on working with frameworks and engines, and less on writing basic Ruby code, so it has been a nice change of pace.

One of the first challenges for this project has been getting the gem to build and install correctly. We use bundler to install and manage gems for our projects. Awesomely, we can also use it to build our gem too!

Here is a short outline of the process.

  1.  Use bundler to create a scaffold directory for the gem. This is nice because it takes care of a lot of details that are potentially easy to forget, like listing all the files that should be included in the gem.
bundle gem <GEMNAME>
  1. Write your gem! (no, it didn’t go that quickly, but you get the idea)

  2. Build your gem! A hint here is that you need to include the version number in your build command. Also, include the .gemspec file ending. (UPDATE: This is not where you include the version number. That is later!) EX: gemname.gemspec

gem build <GEMNAME>.gemspec

This will build your gem in the directory where you run this command.

  1. In the same directory, run the install command:
gem install <GEMNAME-version>.gem

It did take us quite a while to get to this point. We definitely had some malformed files and/or structure in our gem such that it either would not build or would not install. A few of the problems we had:

  • Bad require statements – It does not like it if things are named badly, or if you are trying to require '' or similar. I can’t remember why we thought we needed it, but you don’t! Don’t do it!
  • Incorrect naming or file structure – The gem builder/installer really really wants things to follow a semi-strict naming convention. Inside lib/, the main .rb file needs to be named the same as your gem name. If you have any additional code files, those need to be stored inside a folder that is named the same as your gem and main file.

    ├── wikiwhat.gemspec
    └── lib
        ├── wikiwhat
        │   └── api_call.rb
        └── wikiwhat.rb

The final challenge was to be able to require it in IRB and run a command!

  1. Open IRB and require the gem:
require 'GEMNAME'

If it returns true, you’re 99% of the way there!

  1. Run a command! Obviously, this one is going to vary from gem to gem. If it works the way you expect, you are done! In our case, we ran our call method:"Albert Einstein")

And got back the first paragraph of the wiki article on Albert Einstein, just like we wanted. Yay!



  1. So far, we have mainly used this great guide from

  2. I also really enjoyed this podcast on Ruby Gems from Ruby Rogues.

Listening for Events with Backbone Views

This is something that I’ve learned before, and I think I even have it in my notes from when we first learned this, but on Friday, we used two ways to listen for events in Backbone, and I wanted to really solidify this in my mind so I stop getting confused!

One kind of events we can listen for are browser events like click, hover, or focus. The way to ‘listen’ for these kinds of events in a Backbone View is to use an events property in the Backbone View, like so:

events: { '.delete click': 'removeComment' }

The property of the events object is what event we are looking for. In this example, we are listening for a click action on something with the class ‘delete’. The value of the property is what View property should be called when the event occurs.

The other kind of events we can listen for are Backbone events. These are events like ‘add’, ‘remove’, or ‘change’ in Views, Models, or Collections that can trigger further actions. They are set via the listenTo(); function in the initialize property in the View, like so:

initialize: function (options) { this.listenTo(this.collection, 'add', this.addCommentToWall); }

Here, we are saying that we want this instance of the Backbone View to listen to the instance of a Backbone Collection that has been assigned to it. It is listening for something to be added. When something is added, we want to call addCommentToWall, which is a property of the same instance of the Backbone View.

Recap: I have learned two ways to listen for events using Backbone.js. The events property is for listening for browser events. The listenTo() function in the initialize property is for listening for changes in backbone objects.

Git: Adding Remote Repositories

Git and version control are some of the wierdest and funnest things I’ve been introduced to. I love the idea of taking continuous snapshots of the small steps of my work, and then being able to sift through them and pick the ones I want. I think I’m still at a fairly basic level, but within that context, I’ve learned so much!

Remote Repositories

Remote repositories are basically copies of your git repo that are not stored on your hard drive. This seems kind of obvious, but didn’t really click for me until I learned that you could have as many remote repositories (remotes, for short) as you want!

Step 1: Take a look at the remote repositories you already have.

git remote -v

You will see a list that looks something like this:

origin (fetch)
origin (push)

Or like this, if you have multiple remotes already set:

mks (fetch)
mks (push)
origin (fetch)
origin (push)

You can see the remote name (or ‘alias’, if you want to get technical about it) followed by the URL that actually describes the location of each remote repository.

All of my remotes are on GitHub, but you can have remotes on other servers, or so I’m told. I have not tried to set up my own git server yet. :D

NOTE: The repo you clone from and/or the first remote you add will by default be called your origin. So when you are reading tips and tricks about Git, origin is just your ‘default’ remote alias, which may or may not be true for your particular repo. This may or may not cause a lot of confusion and/or frustration, but checking your remote names/aliases will save you a lot of troubleshooting time.

Step 2: Add a new remote.

git remote add <ALIAS> <url>

Fill in ALIAS with the name you want to use to access that remote. You can’t use origin if you already have an origin assigned. I try and give them easy-to-remember names based on the GitHub username. For the last several weeks, we’ve been working on the same repos in class, with new branches every day for that day’s lesson. Instead of making a million folders with a million copies of the same repo, I added a second remote as ‘mks’ that pointed to the correct repo on the makersquare account so I could just update my local copy of the repo every day! I added a third remote that pointed to my partner’s repo of the same assignment.

Step 3: But I want to change the remote that origin points to!

It’s cool, you can do that! First, remove the current origin:

git remote rm origin

Then, check make sure you removed the origin:

git remote -v

Last, add the new origin;

git remote add origin <URL>

And just to be sure, check your remotes again:

git remote -v

Ta-dah! New origin added!

Github repo confusion

Last week, I accidentally cloned down the wrong repo from GitHub. Whoops! I forked the repo for one of our class assignments, but I grabbed the URL for the MakerSquare repo, not mine. Fortunately, there was Google to the rescue!

Turns out, this is actually a little bit easy, though I read through the first 5 or so google search results before I did anything. This blog post was the most helpful because the commands were explained very nicely. It probably also helped that it was the 4th or so thing I read, so I was beginning to understand what I needed to do.

I did the following:

1. Check the current remote to make sure it is actually what I think it is

git origin -v

2. Remove the current origin

git remote rm origin

3. Add the new (correct!) origin

git remote add origin

And tah-dah! All fixed! And in even nicer news, there is actually an even easier way of doing this that might be newer than said blog post. On GitHub Help, there is some information about using

git remote set-url

to do the same thing as the above step 3 and allows you to skip step 2 entirely.

Since this was an early mistake in a very simple single-branch repo, I didn’t have to take any other steps to make sure the HEAD was in the right spot or that any changes were correctly synced.


Today, I am very thankful that I have ‘previous experience’ using the command line. Turns out, I need to stop underestimating how much I know, because turns out, I remember quite a lot! Which was really useful, because today, we jumped right in to learning about git and github, and I think I understand! No longer do I have mysterious incantations or un-remember-able commands. I (mostly) know what I’m doing with basic Git commands. And I’m comfortable typing stuff into the command line, and even more comfortable when I know what it is supposed to do. As part of our exercise today, we wrote up a nice little ‘git cheat sheet’, which will really come in handy while I get more practice using git.

I’m also really pleased that ‘writing webpages in Notepad in college’ translates really well into ‘I remember how to do this’ when doing our beginning HTML and CSS work. Thanks, past self! You did good!

I also learned a valuable lesson in making sure you have scrolled alllllll the way down to the bottom of the documentation for the thing you are having trouble with, because there might be some help all the way down there at the bottom. I’m not sure if I could have fixed my problem with the boxen install with that knowledge, but when I saw that today, I definitely had a bit of a ‘d’oh’ moment. Lessons learned all around.

Development Environment: Ready!

The folks at MakerSquare have recommended OSX for the course, and I had an exciting time getting everything updated and installed. I ran into a few problems getting set up, but thankfully, none of them were at all un-fixable, though I still have a lingering  error message I keep seeing every time I open Terminal. However, it can wait until tomorrow, and this seems like the sort of situation likely to get me into trouble if I try to mess with it myself. I have at least enough knowledge to get me into trouble, so it seems the best plan to wait until I have some experts in my immediate vicinity. My familiarity with the command line in OS X is largely from a class on phylogenetic analysis, which is to say I was largely typing in things as written on a worksheet or projected from the instructors computer at the front of the room, so there is a lot I know I don’t know.

I’m excited to learn about the tools I’ve installed. All my previous experience has been with the vanilla terminal, but it looks like we have some interesting things! So far I’m really enjoying SizeUp. I’ve been working with Windows 7 at work, and I really enjoy the automatic window resizing, so bringing that to the Mac is pretty great! I don’t know if I’ve been this excited for a first day of school in a long time!

Calculus, physics, and French, oh my!

I have been slogging a bit in the Ruby prework, and I’ve figured out part of the reason I continue to feel unsure about what I’m learning.

When I was taking calculus 1, I did the best on the sections where I went to office hours and watched the professor solve problem after problem. When I was taking physics, I went to office hours and watched the professor demonstrate the process he went through to solve problems. I also practiced the problem-solving techniques over and over to really understand how to approach different kinds of problems. I’ve never been closer to reading French fluently than when I took F306 <<Roman et poésie>> (Novels and poetry) and was reading, speaking, and writing French for hours every week.

With Ruby, I haven’t watched enough experts solve problems, I don’t (yet) have a teacher who can explain their problem-solving process, and I just plain haven’t been exposed to enough code, Ruby or otherwise, to seamlessly follow along with what I’m reading when looking at code. While currently frustrating, I am feeling more confident that I know how to fix the problem. More Ruby practice, here I go!


Taking a big leap!

I am so thrilled that I’ve been accepted into the Fall 2013 class at MakerSquare! I have dabbled in little bits of this (HTML and CSS from 2005) and little bits of that (a really cool but entirely too short Software Carpentry workshop). This is something I’ve had the itch to really dive into for a long time, but never had the time (a cliche, I know).

I’m also a bit nervous, as I was a bit late to the game, and have a lot of prework to do before class starts. Fortunately, the basics of HTML haven’t changed THAT much since I last tried my hand at HTML. 

My favorite thing I’ve learned so far is how much cooler CSS is than I thought it was. Granted, when I was first introduced to CSS I thought it was pretty cool, but CSS3 can do so much more than I remember! I love that you can make whole awesome elements out of HTML and CSS code without needing images! 

I also am glad to finally understand a situation I ran into a few months ago. Firefox had eaten the favicons for a few of my bookmarklets (again), and I was trying to find the favicons so I could manually add them too the bookmarklets, and I kept running into the problem where the icon I wanted was on one large image with many other icons! But thanks to CodeSchool’s CSS Cross-Country class, I understand! It’s a clever way of having all your icons load when the page loads so you can do fancy things like mouseovers with CSS!