programación y pataletas

"If everything seems under control, you’re just not going fast enough."

Tue, 09 Mar 2010 12:11:20 -0500

““If everything seems under control, you’re just not going fast enough.””

- Mario Andretti

MC's de Mierda

Mon, 08 Mar 2010 16:53:14 -0500

Mucha gente habla sola cuando en el váter caga su mierda, si el váter es el que te habla eso se llama esquizofrenia.

Traducción de market-speak a español del comunicado de Bancolombia

Mon, 01 Mar 2010 15:57:16 -0500

Este sábado 27 de febrero se están aplicando de forma controlada algunos procesos correctivos en los canales transaccionales por motivo de la falla técnica del día de ayer.

El nuevo sysadmin de la India se tropezó con el cable de luz en los servidores mientras le enseñaban a jugar frisbee ultimate.

Dichos procesos pueden limitar momentáneamente algunos canales y servicios del banco.

Quiebren la alcancía del marranito si van a salir de parranda este fin de semana.

Lamentamos los inconvenientes que este incidente puede ocasionar en nuestros clientes y usuarios.

Se nos perdió la platica de su nómina, pero relajese que algo se hace.

El equipo responsable del restablecimiento del servicio está dedicado y concentrado en estos procesos de ajustes.

Contratamos al hijo del gerente que tiene 15 años pero que al parecer es un “mostro de los computadores”.

Agradecemos su comprensión.

Y si no les gusta los vi corriendo pues pa’ otro banco, perras.

Power Users

Wed, 27 Jan 2010 20:55:05 -0500

Power Users

"The problem is that the “world out there” is constantly changing, everything is..."

Sun, 17 Jan 2010 10:51:45 -0500

“The problem is that the “world out there” is constantly changing, everything is impermanent and it is impossible to make a permanent relationship with anything, at all.”

Uno en un millón. 6,706,993,152 seres humanos. Buena suerte con eso.

Wed, 11 Nov 2009 12:34:25 -0500

Uno en un millón. 6,706,993,152 seres humanos. Buena suerte con eso.

"There’s something about being in a closed space up here, with no way out, and with no control over..."

Fri, 23 Oct 2009 12:42:27 -0400

“There’s something about being in a closed space up here, with no way out, and with no control over the guy in the cockpit that just gets to me,” he says.”

- Añadir la imposibilidad de fumar y me tienen ahí, retratado

A wiki is not a replacement for real documentation

Thu, 15 Oct 2009 16:31:23 -0400

Note: The latest version of this document can be found here

For those interested in the documentation tweet (http://twitter.com/febuiles/status/4892316133):

For the purpose of this discussion, I’ll divide documentation in two categories:

Guides
Reference

They serve different purposes, a guide is supposed to take you through a piece of software and all its capabilities, usually with examples and detailed explanations.

Reference guides usually serve the experienced programmers find what they’re looking for. They’re not interested in all the verbose text around a function explaining how it came to life, they just want a short overview of what it does and maybe an example.

The Guides

Rails Guides (http://guides.rubyonrails.org/) are a great example of what a guide should have, lets take the Migrations guide (http://guides.rubyonrails.org/migrations.html). You get the chapters list (table of contents) on the right so you can jump to any section you need, you get an explanation of what a migration is near the top (in case you don’t know if that’s exactly what you’re looking for), you get a “Here, this is what you’ll learn today” paragraph so you can see if something’s relevant for you, and then you get a book-quality guide with code examples and tips (both are obvious to the reader, in different colors and in their own boxes). And the best part of it? Everything’s in one page, if you want to find something you’re one Cmd-F away from finding it. If you can’t learn what a migration is after reading that document you should just stop developing web apps (with Rails) and go raise pigs (I’ve heard it’s a nice profession with great bonuses and a lot of useful real life experience).

On the other hand, you can also get stuff like SproutCore’s website (http://www.sproutcore.com/). If you’re like me and you wanna see what Javascript frameworks are up to you’d go click on the “Learn More” link in the bottom to go taken to their wiki and there, after trying to visually parse a thousand links you’ll find the “SproutCore Basics” page (http://wiki.sproutcore.com/Basics-Introduction). You’ll see the 2 main problems with guides in that page so please pay attention:

See the “Older docs. Moving to a new guide or removing.” comment? Yeah, that happens, all the time. It’s a wiki and its distributed nature (pages everywhere, related together only by links[1]) hides the fact that some pages are out of date. Marking them as “Out of date” might help the users, but the developers might not notice it if they don’t usually go to that page.
And this is some serious shit. Notice how the outline is divided in 4 sections? Ok, that’s good, now, try to find the “Next” button. Go ahead, I’ll wait for you here.

Oh, you didn’t find it? Neither did I, don’t worry. Go ahead and click on (1) Introducing SproutCore.

You take your time, read through the whole thing and then realize that HTML5 will save the universe, great. Now, how do I move to section 2?

Oh right, this is a wiki, there’s no sequential structure or anything like that, this is just a collection of documents. And here lies the problem with this system, it might work for documents with 4 sections (it’s only pressing backspace four times and then clicking another four, not that bad), but what happens when your piece of software has hundreds or thousands of pages (see Emacs: http://www.cs.cmu.edu/cgi-bin/info2www?(emacs)Top) ?

Good luck trying to find how to configure your OpenVPN through the US gateway in OS X (http://wiki.witopia.net/wiki/Main_Page).

The References

As said above, the reference guides are usually a bunch of APIs documented in the same place with short overviews of what something does and maybe an example of the thing at work. A great example of a reference guide is the RDoc documentation for Ruby (http://www.ruby-doc.org/core/) [2]. If you know what you’re looking for you’re one Cmd-F away from finding it (again integrated browser search, start to notice a pattern?).

The thing with references is that sometimes you will be looking for a lot of stuff instead of looking for a specific fact (how do I convert an ASCII string to Unicode in Python? Let’s take a lookt at str). This makes having all the information in a concise format in the same page a gift from the gods.

Python is pretty good known for having this terrible documentation which tries too hard to be a reference and a guide at the same time. Google for “python string” and the first result you’ll get is “Built-in Types”, a page that not only describes strings but also describes lists, tuples, floats and more. It’s as verbose as it gets and it’s missing critical stuff like a way to easily move between the methods, but it’s still better than a wiki becase you know that all the information is there, on that page.

There’s one more issue with wikis and that’s keeping them updated. A reference like the RDoc one is easily updated every time you updated the code because it’s kept there in the same place as the source code. With a wiki you might bet a bit lazy and tell yourself that you’ll update it as soon as the 30000 RSpec expectations finish running. While they execute you’ll go for a coffee and meet a pretty nice waitress at the cafeteria, you’ll talk to her for a while and boom, there goes the updated documentation.

Conclusion

I hope this helped clarify my frustration with Wiki documentation (I blame OpenSocial). If you have any questions, suggestions or criticism you can reach me at federico.builes@gmail.com

[1] Wiki systems usually have to fix this when they “reach critical mass”, search for any entry on a person’s life, a country or a virus in Wikipedia and you’ll find a bunch of [nice] chrome on the right side and on the bottom with a lot of useful information like the facts for a category in the right (area, population, GDP. and more when you’re looking for a country) or the topics in the bottom (history, geography, government). This kind of structured approach is usually frowned upon by Wiki proponents but even they realize it’s the only way to categorize a lot of information.

[2] It’s great in the sense that it’s easy to use and serves its purpose just right. The quality of the documentation itself could be a bit better.

[3] Another option proposed by @diegoeche in Twitter is using literal programming (Knuth’s idea for software). It might be worth checking it out.

Yo también tuve 15 años.

Fri, 09 Oct 2009 16:17:00 -0400

Yo también tuve 15 años.

"If you observe a really happy man you will find him building a boat, writing a symphony, educating..."

Wed, 26 Aug 2009 16:49:18 -0400

““If you observe a really happy man you will find him building a boat, writing a symphony, educating his son, or looking for dinosaur eggs in the Gobi Desert”.”

- W. Béran Wolfe

Back to Basics

Fri, 14 Aug 2009 00:21:00 -0400

Lista cualquiera

 (1 2 3 4 5)

Lista con 1 elemento

 (defn)

Lista con 2 elementos

 (defn print-hello)

Lista con 3 elementos

 (defn print-hello [])

Lista con 4 elementos

 (defn print-hello [] (println "Hello World!"))

Resultado

 user=> (print-hello)
        Hello World!

Un programa?

()

"It’s about computer usage as a creative act, something that becomes harder and harder to experience..."

Wed, 12 Aug 2009 18:43:06 -0400

“It’s about computer usage as a creative act, something that becomes harder and harder to experience the more proficient one gets with a computer.”

- Switching Season

Muy viejo...

Fri, 24 Jul 2009 16:30:00 -0400

…para estar diciendo en público que Ruby es mejor que Python, que Rails es mejor que Django, que Git es mejor que Mercurial, que OS X es mejor que Windows.

Fighting for Control of Somalia

Fri, 29 May 2009 23:20:11 -0400

Fighting for Control of Somalia

Cinco años más tarde…

Wed, 27 May 2009 23:48:26 -0400

Cinco años más tarde…

Jaydiohead - Wrong Prayer. Descarga completa del album en...

Mon, 27 Apr 2009 16:14:00 -0400

Jaydiohead - Wrong Prayer. Descarga completa del album en http://jaydiohead.com

"El domingo por la mañana entraba en la unidad de urología, que viene a ser el lugar en el que..."

Mon, 20 Apr 2009 16:09:14 -0400

““El domingo por la mañana entraba en la unidad de urología, que viene a ser el lugar en el que oficialmente reparan pollas…”

- http://www.elsentidodelavida.net/no-folleis

Vitamin String Quartet - A Favor House Atlantic

Sun, 19 Apr 2009 21:29:43 -0400

Vitamin String Quartet - A Favor House Atlantic

When your drummer has recurrent mental breakdowns and runs off in the night, naked, after shows, then you might have a little problem.

Tue, 07 Apr 2009 00:11:56 -0400

Ando escribiendo un pequeño artículo sobre el álbum “The Shape of Punk to Come” de Refused, y mientras lo termino, quiero dejar esta pequeña joya que me encontré en una entrevista a Kristofer Steen

If you were to offer an aspiring punk band any advice now, based on your experiences, what would it be?

One: when your drummer has recurrent mental breakdowns and runs off in the night, naked, after shows, then you might have a little problem. Two: when your singer writes a lyric featuring the chorus, “Fuck you for pissing on me / Fuck you for pissing on me”, directed at the other members of the group, that might be a good time for a little talk. Three: if two of the members of your group are romantically involved with the same person, who is also your tour manager, resulting in dramas on a daily basis, sit down and discuss the situation.

Los Oompa Loompas de la Ciencia

Sat, 04 Apr 2009 21:34:00 -0400

Cada día me siento más agradecido de poder alejarme de los ingenieros de sistemas*. Me doy cuenta de que una de las facetas más patéticas de su vida es el poder encontrar diversión atacando a otros, rebajando y ridiculizando para ellos, de alguna manera enfermiza, poder ser felices. Y aunque no es algo exclusivo de los “oompa loompas de la ciencia”, creo que es en esta profesión donde mas abunda este prototipo de seres humanos.

Estoy convencido de que se debe a la falta de desarrollo personal, nunca fueron capaces de interiorizar sus personalidades (no creen en lo que son, y no son lo que ellos creen), porque si hay algo que ellos odien mas que a las otras personas es a sí mismos.

Si no tuviera un problema con ellos diría que siento pesar, porque siempre al final del día van a tener que enfrentarse con su propia sombra, un personaje oscuro que los seguirá hasta el final de sus vidas. Pero no siento pesar alguno.

Para muchos de ellos, espero que ese día no se demore mucho, y puedan por fin encontrar descanso.

* Por ingenieros de sistemas me refiero a la gente que estudia Ingeniería de Sistemas, a los sistémicos como los llama Hernán. No confundir con los programadores.