Yesterday at a party I was talking with a guy who works for IBM doing "agile" development. It was the first time I had a chance to talk with someone who actually does this, for a length of time, so I could play Q&A to figure out how it maps onto how I do software development. I was pretty sure it did. 

I think what I called We Make Shitty Software is in other words the same thing as the agile process. Whatever it's called, we all acknowledge that our software is imperfect, it's a process, but we're working to make it better, and more responsive to users.  

I may have other concepts to contribute, such as Narrate Your Work, and Instant Outlining, which have made big differences in the development process for me and the people I have worked with. We developed Radio UserLand in 2001 and 2002 with instant outlining. And I've been doing Narrate Your Work, which is an individual thing, for well over a year. It gets better all the time. I can't do any development work these days without telling the story in my worknotes site. 

For me, the development process itself is really the work I do. Because that's where my tools have the greatest impact. Not just for software development imho, but in other project-oriented activities. I think all kinds of production are better managed with NYW and I/O. And someday there may be movies or paintings that are iterative, so will benefit from the agile process. Perhaps there already are? 

Another thing that works is the idea of code as a weblog. At the top of each part there's a section where each change is explained. The important thing is that with elision (expand/collapse) comments don't take up visual space so there's no penalty for fully explaining the work. Without this ability there's an impossible tradeoff between comments and the clarity of comment-free code. No manager wants to penalize developers for commenting their work. With this change, with outlining, that now works.  

Here's an example of a piece of code that's been developed iteratively over a couple of years. Look in the Changes section near the top, you'll see that it tells a story. This is real code that's very much deployed, in fact the text you're reading now was rendered with it (as was the code listing). You might see it more easily in a screen shot of the same bit of code in the outliner-based code editor we use. 

We did this at UserLand, starting in the early 90s. There's code in our system with over 15 years of mods to it made by different developers, and you can, if they were careful about it, know what they were thinking as they changed the code. The code tells its story. I have never seen any other devteam do this. If there are other examples, I'd love to compare experiences. 

These days I include links to my worknotes in my code, because there is a level of detail I will go into on the website that I won't go into in the code. One of the reasons is that the project is not the same thing as the code modifications. The reasons for making the changes may apply to several objects in the code. So it makes more sense to explain it outside the code. In other words there's a level above the code. That's where my worknotes tie things together.  

And an example of day's work in the worknotes site.  

Update: Another principle -- when you're developing something new, where you don't have much prior art, get something usable as quickly as possible. Your thikning becomes much more concrete once you have something that you're actually using. Answers come more quickly and you end up throwing out less work, the blind alleys aren't as deep. That also works for the code too. You work much more quickly as soon as you can start regression testing each iteration. The longer you write code without using it, the harder it's going to be to debug it.  

Another one -- prior art as a design method. That's a big one. Always see if someone has done this before. If so, why not leverage all they learned. And you get to use something before you have to write any code. This led to one of my mottos: Only steal from the best.