Documented?

So, I'm taking over the technical management of a web service. One of the first things I did was talk to everyone, mostly to check the temperature. The kinds of questions I asked were basic. If you ask a basic question, you get a better answer. And one of those questions was What can we do better? The one unanimous issue was that we needed better documentation.

Great. Only two problems with this.

1. Most of the team doesn't write well.
   
2. In the past, nobody has gone out of their way to really make documentation happen.

Why I point this out: most teams probably think that this is just a scheduling problem. As if you just added some time for Documentation, the problem is solved. I think if you just added more time for documentation, people will just half-ass some crap on the wall and probably spend the rest of the time you slated for documentation surfing the intertubes.

I need a strategy. I need a system that will help bad writers get better incrementally. Which means that everything must be painfully obvious. The first pieces of the puzzle are the stuff that actually exists, which are the most important parts, anyway.

• Code/API Documentation — What does your code do? Especially, what side effects are there?
• Adminsitration Guide — How do we run the system?
• Users Guide — How do users run the system?

The other part is planning. Essentially, you need to identify groups of features, and then answer two big questions for each feature set. One, what's the business value here? Or, how do we get paid? Two, how is this thing going to work?

I'm not sure I've not forgotten about something completely hugemongous.

Women Are Out of The IT Compartment

Why do we create stupid compartments for everything? At first, I thought it was just Americans with their shared cultural stupidity:

• You can be black, or white. Or maybe brown or yellow, but those aren't really used. But I've actually checked White on forms in school.
• Red state means religious conservative Republican, blue state means agnostic liberal Democrat.

But you know what? When it comes to programming, the whole world shares another category:

• Programmer - a guy who likes tech. Pretty geeky, usually.

It's a shame, really. And it's everyone's fault. Another blog flipped a switch about the little ways we help permeate the chicks don't do IT thing. In the article, it was shopping, where a salesman kept ansering the brother, instead of the sister who asked the questions.

The entire time we were in the store, despite the fact that it was my sister asking the questions, despite the fact that I only answered questions that she asked of me directly (in other words, I was there to help her, not to help the sales guy sell to her), almost the entire conversation was spent with the sales guy talking to me, even if he was answering her question. His body language was unquestionably that of, "She's clearly not capable of making this decision herself", and addressed everything to me, despite her repeated attempts to catch his eye and have him talk to her, the actual purchaser with the question.

My concern is that this is a kind of "shared cultural discrimination". You stick a saleswoman in there answering questions, and most of the time, I think you'd get the same result. I don't think this is a "boy's club" sort of situation, but a general acceptance that women just aren't interested and don't really know about this sort of stuff.

Build some scala-swing documentation for 0.1

Beta? I don't need no stinkin' beta!

One thing about HTML documentation, I love them links. Especially the ability to navigate up and down the inheritence heirarchy. Mmm... hierarchy.

But the new scala-swing project, which looks interesting, and is included in the latest release candidate for scala, has no documentation. Ergo, I went about tweaking the src jar just to get things a goin.

First, I unjarred the scala-swing-src.jar file into the directory scala-swing-src.

Second, I changed the scala.home property to my scala distribution, which I had downloaded.

Third I added this code to the build.xml file.

      <taskdef name="scaladoc"
        classname="scala.tools.ant.Scaladoc">
        <classpath>
          <pathelement location="${scala.home}/lib/scala-compiler.jar"/>
          <pathelement location="${scala.home}/lib/scala-library.jar"/>
        </classpath>
      </taskdef>

      <property name="docs.dir" value="api" />
      <property name="sources.dir" value=".." />

      <target name="docs">
        <mkdir dir="${docs.dir}"  />
        <scaladoc
          srcdir="${sources.dir}"
          destdir="${docs.dir}"
          deprecation="yes" unchecked="yes">
          <classpath>
            <pathelement location="${scala.home}/lib/scala-compiler.jar"/>
            <pathelement location="${scala.home}/lib/scala-library.jar"/>
          </classpath>
            <include name="**/*.scala"  />
        </scaladoc>

Third, I ran the command ant docs from the scala-swing-src/doc directory, and blammo, I've got scaladoc API.

Note: this is not a true step-by-step howto, because it's getting late. You will have to engage your brain to fill in 1-2 blank spots in the steps above.

tickets != tasks

My company uses trac, which so far, is my favorite project management tool that I've used. It gets out of the way for the most part. Really it is perfect for a group of code monkeys. But it is missing something very important - scheduling.

The basic unit of Trac are tickets, assigned to milestones. This works well when it comes to reporting problems, but also pretty nice when you need to see the issues you are solving. That's the core of a ticketing system. Issues happen, you write a ticket. A series of issues tracked by milestone do a good job of saying this is what happened, what will happen, what we want. It does not, however, say when anything will happen.

To say when, it's better to start with an issue, and then try to define small steps that get you going. This seems like a natural one-to-many ratio of issues to tasks, and that's true. But the real problem lies with the fact you rarely can take the one issue and accurately define the many tasks. As time flies, your many will grow, and change, as you learn things, specs change, whatever. Ultimately it is very hard to embed task analysis inside of an issue-focused system.

While tasks start their lives once someone is taking on an issue, the culmination of tasks needs to be seen in the perspective of time. In fact, I would also like to see things like milestones in such a calendar as well. A project calendar like this would spot the when of a project. And leave the tickets and milestones to simply define the what happened.

Time to market isn't everything

Tim Bray brings up an argument I have heard too often - time to market kills your competition. I think it is important, yes, but it does not kill competition. There are too many important examples of time to market not killing your competition.

Let's look at some of the most important high-tech goodies out there. Internet Explorer for web browsers, Google in search, iPods in music players. All of these did not exist when competition "had the market". They came in late and took the market by being better in different ways. IE was easier to set up in the OS - you might say illegally easy to set up, but there you go. Google was simply easier to find what you really wanted. iPods were all around superior devices to any other mp3 player I used - much easier to navigate.

But the key aspect here is that these players were different and significantly better than their competition. If you have the market, and you capitalize on that by learning and adjusting quickly to what people need, it's yours. But if you stop innovating, it's just a matter of time before folks flock to something else.

Monkeys don't make good admins

Code monkeys are pretty damn amazing at some complex tasks, like climbing trees, or peeling bananas. We do not, however, like computer recipes. An example computer recipe: to upgrade Foo, check script X on machine B and then restart application Y on machine C. We don't become programmers to follow recipes, we want to make them and have the computer do them for us.

You better be careful if you make your code monkeys follow recipes. Many of them, like me, get irritated. Enough irritation, and we get angry. When we get angry, we start throwing poo. And then you just end up with shit everywhere.

What? No delete?

Today I was shocked to learn I could not delete a simple web page connected to my domain on Yahoo's domain registration site.

Recently, I moved my blog from a shared hosting site to blogger. I had been using it to learn some web design, and now I've decided it was more important to spend the extra time learning how to write. Leave the graphic stuff behind for now, and just point the ol' domain at blogger, which is easy to do.

Except the yahoo CNAME forwarding will forward www.tristanhunt.com but not tristanhunt.com. Which is lame, because I don't like www. because it makes no sense.

While experimenting with just having a simple page do a manual redirect as a kludge, I learned two things about the Yahoo system:

1. They do not allow you to edit your simple landing page for your domain
2. Once generated they do not allow you to delete it.

Check for yourself.

I'm sorry, but I do not care who you are. You can make people jump hoops to delete things that might mess up functionality. But not allowing deletion? I'm sorry, this is just stupid.