Posts (page 2)

    I was going through my feeds today and read a really great article from Kathy Sierra about Demoing Software and it got me thinking about what other great blogs I read. I just wanted to share some good links for everyone to enjoy, so here you go!

Creating Passionate Users - A great blog from Kathy Sierra and the people behind O' Reilly's Head First series. A great read.

Joel on Software - Joel Spolsky's interesting blog about a range of software topics from usability, design, and anything else related to software development.

The Java Posse - A great podcast about everything Java, after listening to the episode you can go check out all the links they have to the stories they covered.

O' Reilly Radar -  I have nothing but good things to say about this blog, it has many authors from O' Reilly Books as well as Tim O' Reilly himself.

    So here are just a couple links to other blogs I have been reading, and they will keep you busy for hours reading. Creating Passionate Users has so many great posts that its just a treasure trove of information when you start looking at older posts. Anyways, check out those sites and also check out my neighbors here on Vox, they have great things for you to read.

    My parents just told me a couple days ago that they have been trying to get me a Wii for Christmas. Naturally, I was excited to hear the awesome news since I have wanted a Wii for a while now. Well, there was one small problem. They live out in the middle of nowhere so I have to try and get one here. "No problem," or so I thought. Today the Wii shipped and by 2pm they were gone from everywhere! I should have expected this, but it still sucks! Anyways, I'm done ranting and hopefully Nintendo ships some Wiis shortly after Christmas so I can finally get some some. *sigh* 

    So its been a while since I have posted, but being a dad and having finals coming up will do that to you! I just wanted to post a quick update that I'm still here, just a little busy.

    Now on to the real news! My daughter Aubrey Jeanne, was born on Friday, December 1st and weighed in at a whopping 9lbs 9oz. and she is the cutest baby in the world. Amber is recovering well from the c-section and we have been back home since Monday the 4th. Other than that, Aubrey is sleeping well, she eats a ton, and is generally a pretty mellow baby right now. So there is my quick update on whats been going on lately and hopefully I will have my next post up pretty soon. See ya.

Yesterday was the first snow of the season that actually stuck overnight. Snow drives me absolutely insane, its just too cold! I am most definitely a desert person and I can handle heat really well, but I can't stand cold at all. In short, snow sucks, heat rules and I'm done rambling now. Anyways, heres to you old man Winter, I hope you don't stay long.

Until I am a father! Its crazy to think that its been almost nine months since we found out Amber was pregnant and now it is almost time for Aubrey to come out. Its such an exciting / scary thought to know that I am going to have a little baby that is entirely dependent on Amber and me.

    Am I the only person that seems to find many open source projects are sorely lacking in documentation? It seems that there are many projects out there that hardly even have a wiki to store any information about the project. For example, Apache Maven is notorious for having no documentation or (worse) inaccurate documentation throughout the project and its plug-ins. Its really a sad thing because Maven is such a great tool, but often times I have to spend an hour or two looking up why this won't work or why this plug-in is incompatible with with that jar etc... This lack of documentation is one of the reason much of the Java community still stays with Ant for their builds. It just takes too long to migrate a project's build over to Maven because you have to spend hours looking up how to do even basic things.

    I'm not bashing the developers though, its great that they are contributing so much to the open source community.  I can personally attest to not wanting to write documentation because my ego gets the best of me and it feels 'below' me or I just can't be bothered by writing 'stupid' documentation. Instead, I am just suggesting that we developers start realizing that documentation is not just the boring part of coding, but instead is an important piece of great software.

    I tend to break documentation down into two different categories: code documentation and user documentation. Code documentation is a place where many developers, including myself, have misconceptions or bad habits. There are a couple different things we need to think about when you are documenting your code. First, we need to remember that other people actually do read the code we write, and it is important to remember that when you comment code. Someone else IS going to read what you put there. We programmers are a lazy bunch and we don't like to write too many comments. This is a good thing actually, to quote an overused statement 'your code should document itself.' That quote comes with a clarification on what 'self documenting code' really means. It doesn't mean that you don't have to write any comments in your code. What it really means is that you should be writing code that isn't so overly complex that it needs comments to explain what it is doing. Instead, much of your code should be simple and straight forward. This allows you to reserve the comments for when you do have to write some complicated code or you made a major design decision in your code.
   
    One nice thing about code documentation is that it grows with your project. As you change your code, you change your comments so stay in sync with what it is doing. Documentation that is out of sync with the code is one major problem about documentation that can be solved easily with an automated development process. As all projects should be doing continuous builds, the documentation can be put together and deployed in each nightly build. Maven does this, it wouldn't be hard to do this with Cruise Control or a simple Ant script that you have set up as a cron job. By just spending a few minutes and setting up a build cycle, you don't have to worry about making sure your documentation is up to date. Now isn't that what lazy programmers like us like to hear? I know I do.

    My second classification for documentation is the user documentation. This kind of documentation is designed for the end user, not us programmers. The people who use the piece of software every day will want to read this to understand what they can do with the program as well as where to start or how to fix a problem they encounter. This kind of documentation is the most neglected kind in many open source projects I find. Maven is really bad with this. There have been many times I will need to add something to my Maven build and I spend the next two hours finding out how to get it working because the documentation either wasn't there, or barely covered how to use the damn thing.

     Fortunately, there is at least some automation for this kind of documentation as well. While reading The Pragmatic Programmer: From Journeyman to Master, I came across their section on documentation. They suggest you do this documentation in a markup language such as DocBook so that you can generate many different formats of document from TeX, RTF, HTML, PostScript, etc. This way you don't have to repeat yourself, but you can format the documents in many different formats. User documentation should be just as important as documenting your code. It should not be an afterthought, but instead a first class citizen of your development process. Many projects would have much more success if they were properly documented, for example Apache Maven 2 would have a much greater adoption rate if there was documentation on how to use it! Sure, the mailing list is great, but I shouldn't have to go to the mailing list just to find out how to accomplish what should be a simple task.

    In conclusion, I have found that every successful open or closed source application comes with excellent documentation. Although it may feel like it is less important that actually writing code, it isn't. It makes you think about what you are doing and also helps others know what the thought process was. When you write good documentation, you allow the project to continue with new people and you allow the users to actually learn what they can do with your software. I propose that projects, large and small, should really take a moment to look at their development life cycle and see where they documentation comes in. If your project lacks in a standard way of documenting your code and project, you should sit down and work out a plan to include this in the process. Once you get this process down, you will really see the benefits of accurate documentation, both from the development end to the user end. Happy writing!

What's the most drastic change you've ever made to your appearance?
Submitted by Laurie.

I dyed my hair black and grew it out to shoulder length. I also changed from dressing nu metal (blah) to just jeans and band shirts that actually fit me. It was awesome.