Ionrock Dot Org

The last few few weeks Uche and I have been working on a project. It has been a great experience in that I have learned a ton. It has also been extremely frustrating because it has made clear my skills documenting are terrible. The biggest issue is that I simply don't enjoy writing documentation. There are a very select few who really enjoy documenting the mundane and technical, many of whom I've had the privilege of helping. It is too bad that I didn't manage to pick up a desire to be a better documentarian.

The biggest issue I have is adding enough detail. I might outline the basics, but you always have to consider when something goes wrong. This doesn't mean that every possibility needs to be documented, but having a few obvious routes for debugging can be a real help. Again, what denotes a piece of information is always going to be subjective, but one man's trash is another man's treasure, so you never know when the small reference to a specific class that handles a critical piece can help someone save an hour.

I doubt I will ever be a pro when it comes to documenting. I would rather write code for the time being. It is clear though, that as my code becomes used by more people, it will need better documentation. While now is not the best time, hopefully I'll catch the documentation bug and get my head out Python/Ruby mode for a little more reStructuredText/Wiki Text.

My new job consists primarily of coding in Ruby, and more specifically, Rails. This has been relatively fun really learning a new language, but it is also rather draining. The hardest part is going home and writing Python. It is so easy to sit down, open a few buffers in Emacs and get something done. This is exceptionally frustrating then to go into work, only to battle against the massive amounts of magic that is Rails.

This explicitness over convention mindset is definitely a pythonic idiom. In statically typed languages, explicitness is mandatory, which is why many folks look at things like XML as a scripting solution. In a language like Java or C#, XML is a clean slate to write the operations you want declaratively. The downside though is you end up with oodles of XML configuration files.

For whatever reason, explicitness in Python is rather natural and simple. I suppose this is similar to Lisp in terms of the code being the data. I feel it could be the same in Ruby had Rails not touted its convention over configuration. This has got people thinking it is a good thing, when in fact it is not.

I am not suggesting it is always a bad thing either. A nice convention can save a lot of time, as well as making code easier to read and write. Where it fails though is when convention becomes the rule. It seems to be a subtle distinction, but looking at the community, you see a general feeling of value in meta-programming and DSLs using Ruby. It is ironic to me that this is so popular as most come from Java where XML was used in the same (arguably incorrect) fashion. It is always funny to see kids become like their parents while denying it at all costs.

I've been working on a few projects and I realize the importance of simply keeping up, while not slowing down. Projects need to find a balance between putting out code and adding features while keeping documentation and marketing up to date. It is a very tough problem because each take up so much time. This is especially true when you are writing tests, profiling at the same time as documenting new features, roadmaps, etc.

The solution is simply to try to do it all, but it seems that other successful projects must have some help in order to break past the small project status. Things like full time employees or an enthusiastic user writing documentation might be the key, but even adding users adds more work. Obviously time management is most critical in one way or another, but I have no suggestions there.

Fortunately, improving your practices only gets easier and more efficient. Tools and scripts help a great deal in speeding up the mundane details in addition to solidify coding knowledge. Having fun doesn't seem to hurt either.

Dare blogged about why he works at Microsoft and pointed to Jens leaving Apple in contrasting his experience. One piece that stood out to me was the discussion of individuality being frowned upon at Apple, while being allowed at Microsoft. Jens made it clear that Apple pays very close attention to its image, which means employees are all potential dangers who might put across the wrong message.

In the music industry, this mindset is more or less the norm. For those groups who put across that they have no concern for image, the reality is that "who cares" is their image. This focus on appearance spawned early on with the Internet and applications like Photoshop becoming standard tools. People in music had the chance to publish themselves on the web and utilize tools that helped them rival the main stream acts. This resulted in an extremely competitive market with any and every band appearing as though they were a major label act.

In addition to better looks, the industry became exceedingly prolific. Cheaper recording gear and effects made it possible to get major label quality recordings. This impacted the style of music with more dance based music being put out, but overall everyone was able to get more music published.

Today there is an insane amount of bands who are putting out great music and appear professional. Labels, managers, booking agents, and everyone else work as first round filters to helping bands get beyond local recognition. Everyone understands that the image and impression of the band/label is critical to success. If your image has been associated with something or someone who is not considered "cool", then you are hastily lumped in the same bucket. The problem is that no one has the time to really evaluate music for its quality, so the filtering bodies must be present in order to find anything at all.

This is a very depressing picture, but bringing it back to Apple, it is life. Apple understands that presenting yourself as cool and hip is always going to trump actual deliverables. In the long run, you still need to deliver something, but people ignore bad decisions if the result is slightly less helpful while still looking great.

The iPhone is a good example of a device having some warts that are easy to ignore. You can't text an image to someone. There is no GPS integration with google maps. There is no flash in Safari. The camera is really bad. There are probably more issues, but I still love my iPhone. I have fun using it and that makes it easy to overlook the obvious deficiencies. That is what having a good image is all about, balancing the functions with form such that it is a profitable combination. Essentially, creating an effective image really is creating art. The goals are different in that art measured based on the relationship between the artist and the audience, but the method is essentially the same.

Many people believe that considering art and image is shallow. People think that someone should do something they love because they love it and never taint it with external factors such as making money or marketing. The problem is that doesn't reflect the real challenges of doing something you love. People in sports are forced to learn defense and offense even though scoring points is what matters. If you only pay attention to the most important part, you miss the elegance of the entire world built around the one important piece. It may seem distasteful, but it is a necessary evil that should not be avoided, but considered another challenge in producing something amazing.

While I have been fortunate to find a job I enjoy, it is tough to shake the job seeker attitude. For whatever reason, articles regarding "what makes a good programmer" and the IT market in general, have been fascinating me. It seems with each major change, the focus on working through challenges increases. There is a new impetus to stop running from previously avoided conflicts. Its as though the fairy tales are taken to heart and the most terrible details of life can only be destroyed by a courageous, yet normal, person.

As life is cyclical, it is not surprising that the feelings will most likely fade. In a way the potential freedom the comes from stability can be enticing after seeing the world as nothing but challenge after challenge. With that in mind, it is good to hold onto the focus and courage as long as possible. Even though the feelings and mindset changes, there are often stains left behind that can definitely be seen as an improvement.

In college I started out as a communications major. I have no idea why, but the concept of communications appealed to me. Unfortunately, the actually classes did not, so I switched to history. I enjoyed the classes even though the concept was not very important to me. When I finally got around to software, I was prepared for the crappy classes and assignments along side having a passion for the subject. As a result, life is pretty nice.

The more I think about communications as a concept, the more I believe that technology fails at the nuances. The nuance and delicate intricacies of meaning make quantifying an idea nearly impossible. Technology has always failed in providing the expressiveness by either inundating users with options or simply forcing ideas into incorrect paradigms. My hope is that Bright Content can help to push the issue of expression, so communication can improve over the web.

Currently, we are working on Annotations. The concept is pretty much like a comment. As a person comments (via comment forms or trackbacks), an annotation reflects some data regarding some resource. What is interesting to me is that an annotation will not be limited to expressing some opinion or argument. An annotation can be any "thing" that is applied to a resource where application is not decided by the annotation itself.

For example, an annotation might describe one way to render an Atom entry. The annotation could contain an XML body that describes what relative URL you can find the representation at and what XSLT to use in creating that representation. The annotation itself is nothing more than a resource, but by providing a description of how to apply that specific annotation, it can be applied. By focusing on providing a description, you offer an opportunity to render the application of the annotation. In the comments use case, the application is simply referencing each other. From the standpoint of the annotator, it is pointing to the original content and from the content provider's perspective, the application is simply listing the comments. In other words the way an annotation actually gets "applied" to a reference may or may not be something that is immediately visible in some user view.

It is a subtle concept but it reveals a consistent theme in RESTful services. A resource and representation are not actions in themselves, but are players to be acted upon. RESTful services and design promotes using the file as the interface much like you see in operating systems. I can't imagine a world without files, and yet the web has essentially made an effort to do just that. It has been successful of course, but hopefully, as we realize why, the web can be even more expressive and truly improve communication on and off line.

The Programming Sub-Reddit had about a million articles on monads for a time. The flow of monadic articles has definitely slowed down to a more reasonable pace. I saw an article on using monads in python that struck my fancy. There is a theme in Python and Ruby regarding concurrency due to the previous functional programming flurry. The string of consciousness flowed from functional programming towards concurrency because there was essentially a claim that when you don't have side effects in a function you can easily let other machines and processes deal with the work.

Once you have programmed functionally you begin to see the world in a different place. I'm relatively familiar with it because of XSLT's functional nature. The problem is that when you start getting the functional bug, when you do want to reuse the more traditional procedural style, it is a challenge. Monads then simply make an effort to functionally control the order of operations, or more specifically, the chain of function calls within a certain situation. I'm sure smarter folks might disagree with my definition, but more or less this seems to be a recurring theme so I'm sticking with it.

I'm not going to make this a tutorial or something because I'm not the right guy for the job. I will say that most programmers to need monads because they are programming in a language where order is easy to come by. The place where it could come in handy is in concurrent situations where you want to mix up the order a bit yet still keep control. The obvious problem with threading is that there can be side effects that impact other operations. If I'm using some object or variable and somebody else deletes it before I use it, there is a problem. This is why you see things like using generators and the like to let the flow of things traverse between different objects and threads.

In a way, things like using generators and the like in Python for threading and concurrency, is similar to using monads in something like haskell. In each case you are using the languages inherit features to control flow in concurrent procedures. I'm not very good at this stuff and honestly don't have much use for it in my day to day work, but it is something I'm getting more interested in. Either way, the problems of concurrency are really tough and seeing all the different languages specific solutions makes for a great learning experience on how these sorts of things get worked out.

Lately, playing live hasn't been the most fun. It hasn't been a drag or anything, but there hasn't been much to it. No one seemed to be really enjoying themselves that much and our personalities are not the type to improve the situation, which made playing live to a lukewarm crowd somewhat awkward. Our response was always positive, but there was simply a lack of excitement.

We played last night and it was a really good time. The crowd was into the show and we felt a little more prepared. Of course we have something of a practice addiction, but on a mental level, we seemed a bit more ready than we have been in the past.

I don't have any huge insights here. Sometimes you go through stages where things are simply rolling along. It is nice when you snap out of it and life can be a little more interesting.

Jeff Atwood posted today on PDFs an expounded on what makes it a good format. I mixed emotions about that of course after dealing with PDF in a rather intimate manner. I do love the idea of PDF as far as layout and presentation. Where PDF is a huge hassle is in the fact that it is considered a binary format and not meant to be parsed for editing. This is a huge benefit of HTML and XML, it is very editable. PDFs are difficult to tear apart and put back together because the way the language is within the actual document is not very consistent. You can specify the same content in so many different ways that are all fundamentally different. When you consider this in light of editing, it means you need to consider the author that produced the PDF, which is analogous to having a browser war for anything that outputs PDF. For example, each version of FrameMaker would create slightly different PostScript, which meant different PDFs. Sure it looked the same, but the code that made it happen was definitely not the same.

Browsers deal with different HTML all the time, but they don't have to edit it on the fly in a specific way. Yes, I understand they do parse the output and create a parse tree of some kind, but they don't actually have to send their rendered parse tree out the door to some other browser. It is a subtle difference and I don't know if what I mean makes sense. The nuts and bolts of it are PDFs are now good, but challenging.

Lately I have been reading a rant or two from Zed Shaw. Seeing as I don't make any kind of rash decisions on a community based on the actions of one (especially when that person appears to be leaving it), I took the entire rant with a huge grain of salt. With that said, of the few rails/ruby projects that I have heard of, mongrel definitely ranks up there as important, so it makes me think. I don't know what exactly it makes me think, but none the less it does ;)

Overall I can't say I've had any problems with the Ruby/Rails community. It has seemed a bit younger than something like Python, which is understandable as it is. It also appears that there are quite a few people want to be considered a part of the community. In other words, there seem to be folks who are vocal that haven't actually contributed enough to be considered as important as they make themselves out to be. This is common, so no surprises here. I'm somewhat used the Python community where, from my experience, seems to keep those not contributing to a relative noise level. Again, that is just my experience. I might also simply be sentimental at the moment, so you can take my comments with a healthy grain of salt.

It does make me wonder what makes a strong community since it is definitely arguable that Ruby has a "better" one than Python. While I never really got into Perl, my understanding is Larry Wall made it what it is due to his personality more than anything. Rails is similar in that it made an effort to be opinionated. Python on the other hand is run by the iron fist of Guido, who is actually a very reasonable person who simply asks for evidence along side code. In a way I think I might have just answered my question

I would suppose that gathering a community is more a matter of encouraging people to participate rather than setting a higher set of entry conditions. In a way this could be construed at elitist. In fact, I heard just that plenty of times before regarding XML and Python. The entry level is set rather high to an extent when it comes to either learning the technologies (XML) or participating in the community (Python). I wouldn't blame someone for considering it elitist if the standards didn't make sense (mainly considering Python here as many XML folks have been frustrated by things like DOM).

I am hoping I get to see more positive sides of the Ruby community. In a way I don't expect much of the Rails community because it is so easy to get started. This is a great feature of Rails, yet I would imagine that many people will be able to have success and feel qualified to call themselves experts. I'm not saying they are or are not experts, but rather, it can be easy to *think* you know more than you know. I say this from experience of course.