The Current Distraction from Making Progress

The other day the computer science professor gave out the next phase of one of the assignments, saying that it should take "about an hour" to complete. I've already spent an hour just trying to deal with rearranging my directories and whatnot because I got docked points for not having my directories organized according to their unstated assumptions. Why did it take so long to deal with? Fighting with Subversion.

We've been told that in addition to all of the other things that we learn in this course, that we will also learn Subversion. Really what that means is that at the beginning of the semester, we were given a few cryptic directions of the sort: "First you type this, then you type that, and voila, something has happened! You can figure the rest out if you RTFM." And every now and then we get emails that we are doing it wrong because the way we are doing it breaks some feature that I do not understand, did not know existed, and have no idea how I would use.

For example, we were told that to see our revisions history:. When I use that command, I just see my initial submission. So now when I commit a change, I'll write down the revision number on a post-it note on my monitor in case I need to revert to it later. Since all the students are saving to the same place, every time any student commits a change the current revision number goes up, so my changes are rarely consecutive.

In the current assignment, we are supposed to take the old assignment and do something to it. The TA emailed: "See 'svn help copy' for info on how to properly use 'svn copy.' " And I did, and I tried to make a copy, and it was horrible. Subversion wouldn't let me commit any changes, saying that everything was locked and I had to run svn cleanup. Svn cleanup failed to run, giving me cryptic error messages. I couldn't make sense of TFM, so I did a normal copy, moved all my files around to where they were supposed to be, re-added them, and then deleted the phantom ghost versions from where they used to be. I am sure that this is very bad form and has broken many features that I know nothing about and will never use.

I have no problem with the idea of learning things by RTFM. That's how I learned a lot of things when I was working for the government in Maryland (Yes, that "government.") when I was an undergrad. We were told that we could write programs in C or Fortran; since I had a copy of K&R, I chose C (at that point I had taken two CS classes, both taught in Pascal), and I figured out enough to get my work done. I had to write up my summer research. We could choose between TeX (plain TeX) or some wysiwyg editor that ran on the Suns. I went with TeX; my office of summer interns had one copy of The TeXBook to share among us. (And remember, this was 1994 so there weren't a lot of web pages out there, and if I wanted to use the real internet and not the fake internal one, I had to go to a different office on a different floor of the building.) In grad school, I had to do my dissertation in LaTeX, so I made my transition from TeX to LaTeX by once again reading the manual. HTML and CSS? Again, read about them.

So what's the problem here? Two things, really.

One is that early on in learning both TeX and LaTeX, there were people around to give me general tips about the main ideas. Once I realized that the markup in LaTeX is based on the function of the bit of text and not what you want it to look like, everything started to make sense. (This is similar to how I use HTML and CSS -- I think about what is a paragraph, what is a heading, what is a list, etc.) Instead of telling the software to make the heading of your section larger and bolder and set off by some white space, you tell the software that this is a section heading, and it takes care of what a section heading should look like. If I'm getting frustrated with LaTeX and its insistence on doing things a particular way, then I can think about the TeX metaphors of boxes and glue and try to figure out how to finesse my way to getting things to work like I want them to. The whole trick to solving the problems is to think about them the right way. This is one thing that I really liked about the course I took in the fall when the professor would write code during most of the class period. He would give continual commentary on what he was doing (and why) so I was able to figure out what the right mindset was so that it took less time for things to become intuitive.

The other is the quality of the manuals. In the days before Amazon, I bought myself a copy of the TeXBook from a technical book store in New Jersey. It's an amazing book. The online documentation for svn? Not so much. Or maybe it's just that with the TeXBook I had something that I could hold in my hands and flip through until I saw something that I thought might be helpful and with the svn manual I need to make targetted queries?

I have no insight at all about Subversion. The only commands I use are add, status, and commit. I'm sure it's a lovely piece of software, but I just don't get it.