Archive

Archive for May, 2006

Open Source Documentation, and What I Learned from College

May 30th, 2006

In Jon Udell’s latest blog post speaks about the importance of motivation and context when learners approach topics above their current ability to understand. The example of patients reading current medical research papers online is particularly apt, and one that I know firsthand due to shoulder injuries, and some time spent as a research assistant in my youth.

I completely agree that the open-source world provides a humongous amount of context that I’ve never seen matched by any closed information system. Open source software is typically launched these days with a website, embedded documentation, a wiki, bugtracker, and a discussion list of some sort, and the ensuing conversations around any piece of useful software provide a boon that beats any thick manual hands-down. Software vendors are simply too close to the problem to step back and provide documentation from a learner’s perspective, whereas the adopters, users, and hackers that run open-source software for the first time actively participate in an instant feedback loop where they may share their own experiences with a technology for the benefit of all its other users.

This is something that is typically lost on many, in part due to historically poor presentation and design of feedback systems – when all we had was usenet, obtaining documentation was substantially more frustrating. GNU Mailman systems without a searchable web interface come to mind. Google groups provided a better alternative for a while. Now that we have wikis and bugtrackers that look nice (see the Trac project), the feedback loop presents context in a more digestible way, and drives the creation of more of it.

The other part of the equation of learning above your capacity is motivation, and Jon addresses that both with the medical example, and also with some hiring criteria from Ray Cote.

Ray told me that he’s not looking for people who “know” one or another language or framework, but rather for those who can motivate themselves to rapidly acquire these and other contexts as needed.

This is a great hiring criterion for programmers. Is it difficult to ascertain this during interviews? Shouldn’t be – ask them about projects they do outside of work. Typically, talented programmers who can create motivation for themselves do so in the form of projects. I learned to do this during college, a time when most programmers are required to constantly reinvent the wheel in the hopes of ingraining some repetitive familiarity with the mechanics of programming. As a result, the code I produced immediately after college was absolute rubbish. I don’t deny that the reptition was useful, but it produced no fundamental or sophisticated understanding of programming as a means to an end. Instead, what I learned was generally syntax, familiarity with algorithms, and what can be accomplished through programming. In contrast, my humanities education in the Thematic Option program at USC challenged me in the ways I needed.

Post-college, I did not believe that I liked programming, but i’d take it as a job until I figured out something I preferred, because it paid well. I entered the programmer’s employment market of 2002.

A funny thing happened during the 5 months I was unemployed, though. Left to my own devices, I began to build software to itch my own scratches, employing techniques and methods I had learned from the open source web. Eventually, that time I spent in those 5 months resulted in my employment working for Andy Baio, the founder of Upcoming.org. Although I am but a tyro in the art of programming, I can confidently say that my code has improved since 2002 almost solely due to the context provided by the open source world, directly or indirectly. :)

To summarize, college will not give you any motivation for learning – that has to come from the needs and wants that you have or observe. The context to look for is available, growing, and alive in the open source world. The fact is, as Jon observes, that the network effect surrounding open source documentation is alive and well in other fields where the democratization of information is becoming widespread, and we can hope that it might lead to highly motivated individuals to take on challenges that might originally seem beyond their abilities.

Tech

SOLD: Used Sauder Heritage Hill Executive Desk Set – $500 OBO

May 21st, 2006

Update: Looks like the desk has been sold via Craigslist. Thanks for your interest.

Tech

Why doesn’t our legislative branch use Track Changes?

May 21st, 2006

It seems like every day, I hear about a piece of legislation inserted at the midnight hour into 600-page bills in Congress. It somehow manages to sneak through, only because our representatives somehow don’t notice. After all, who can be expected to read 600 page documents?

Lawyers do it all the time. When lawyers negotiate large contracts, they typically use a feature of Microsoft Word called “Track Changes.” Every time someone opens a document and modifies it, Word keeps track of the modifications, and the next person to open it can opt to see all the changes highlighted in color. This makes it relatively simple to only read the changed/added/deleted portions of the text, and also see who made the change. Lawyers do it, because there are multiple parties with varying interests, who really need to know every change that occurs, because they are actively interested in noticing all modifications to the contract.

Programmers have done it for decades. Modern programs have their beginnings as simple text, and programmers use tools called source control and diffs to achieve the same result. Multiple programmers working on teams need to know quickly who is responsible for certain changes, so that they can communicate and fix problems effectively.

I know of businesspeople, technical writers, and others who use Track Changes to great effect on a daily basis. It saves time and resources. If you’re working in Microsoft Word, it’s automatically available to you.

So my question is, for those people in Washington, what is used to create the US’s legislation? I can’t imagine it’s anything other than MS Word. I’d be flabbergasted if all legislation was continually re-typewritten by aides (talk about a massive carpal tunnel nightmare). Please comment if you have an insight.

As the public who must abide by and pay for these laws and decisions, we must have knowledge of their creation. We cannot ignore a small paragraph of a bill simply because it’s small, so why should Congress have a right to hide its inception? It’s a veritable outrage that we don’t have better insight into the drafting of these bills, when it’s so simple to produce.

I think this is a vitally important piece of pork-barrel reform. Expose all changes to legislative bills to two major groups. The first, and primarily important group, would be the legislative body itself. If they’re tracking changes internally, there’s absolutely no excuse for not noticing changes. The second audience would, of course, be the public. Don’t we have a right to know each change that was made, what representative or group was responsible for that change, and when it happened? This is simple accountability, folks, and it’s so technically available that it’s essentially free if Congress is using a modern document editor.

Note: I understand that Amendments to bills are publicly available through the Library of Congress. I am not interested in the stated intent of amendments, as found here, but rather I am interested in a historical timeline of changes to the documents that become law, viewable in a format similar to Track Changes or modern source control repository browsing.

Another Note: I was able to find certain textual amendments buried in PDFs such as this example. I would like to see this included inside a “track changes” electronic copy of the legislative bill itself, viewable hopefully by the two audiences discussed above. This is the format that lawyers use for final review. I can see no reason to not provide this type of doc internally to the legislative branch, and I would favor its availability to the public.

Tech

An excellent quote for the day

May 11th, 2006

“box wine is ghetto. unless of course you remove the bag and punch a straw through it, like a big wino capri sun. nothing but class.”

Tech

Oh, what a tangled web we weave, when first we practice to denormalize.

May 9th, 2006

Denormalization is a lot like lying.

First of all, when you use denormalized data, you don’t necessarily know that it is true, you just think it is true. It could be a lie, regardless of how much you hope it’s true.

The second thing about denormalization is that once you start doing it, you have to continue to denormalize in order to support your existing denormalizations. It takes a lot of time and effort to make sure that the lies you start to build look more or less like the truth, and to make sure you don’t contradict yourself.

The third similarity between lies and denormalization is that if someone discovers you’ve been lying (or denormalizing) by finding a contradiction, they may become justifiably angry.

There are also the inevitable pangs of regret. If only I had denormalized differently, maybe THEN, we could add feature X. Alas, to unweave the code, it will take at least Y hours to adapt this codebase of lies to work properly.

The final, and potentially most damning parallel between lying and denormalizing, is that both are unfortunately sometimes our most attractive option. When telling the truth about your data will not allow you to serve your users in the way they want to be served, in time frames they are comfortable with, that’s when the slippery slope begins.

I guess, with denormalization, it’s possible to disclose your lies in way that offers the ability to CYA (This data last updated at 2:00:00), and it’s also possible to just pretend like your lies are the truth (Your inbox says there’s new mail, but there are no unread messages when you check it? It must be your computer! Try refreshing the page!). In these cases, the interface may play the role of a politician trying to massage a relationship bruised by lying.

In conclusion, follow a few guidelines when either lying or denormalizing. Be sure to apologize to those who are hurt by your careless and insensitive denormalization. Also, be able to live with yourself in a sea of contradictions. And lastly, it’s okay to do little denormalizations. Adults do it all the time! Just don’t denormalize when I log in.

Yet Clare’s sharp questions must I shun,
Must separate Constance from the nun
Oh! what a tangled web we weave
When first we practice to deceive!
A Palmer too! No wonder why
I felt rebuked beneath his eye;

Tech