software

Today’s release of Lafcadio, 0.9.2, adds a fairly extensive manual to the documentation. There are various tools you can use to write manuals: I wrote mine in Docbook and then used Docbook XSL stylesheets to publish it to HTML. (Thanks to Patrick for pointing out how he did it for Ruby-Web.) But this isn’t really a task where automation can help you much. Writing a manual is a lot of work because writing is a lot of work. This first version took more than a month of my after-work time, which was much longer than I’d expected, and I’m already nervous about how soon it will go out of date as Lafcadio development continues.

Still, I found the process to be worth the time spent. Writing a manual doesn’t just help other people use your software. It also forces you, the writer, to take a bird’s eye view of how your code looks to somebody who’s never used it, which is so easy to lose in the day-to-day when you’re plugging away at a list of granular features and bugfixes. Any strange or arbitrary aspects to the interface become more obvious because the pain you feel in having to explain them probably mirrors the pain of others in understanding them. More than once I found myself thinking “You know, I could just fix this part in the code so that explaining it in the manual wouldn’t take so many damned words.”

Some programmers will tell you that software should ideally communicate its intentions so well that it wouldn’t require documents. This belief is strongest, I suspect, among adherents of Agile methods, and I’d definitely place myself in that camp. But reality often intrudes, and I suspect I’ll never be able to write any non-trivial software that won’t need some explaining.

In the meantime, I’ll probably try to keep updating my docs on a regular basis. I think it’s important to stay close to my users. I wonder what effect it has on the process when you’re in a large technical team, in Microsoft or a major free-software project, where documentation is often delegated to technical writers. Perhaps this arrangement is unavoidable at a certain scale, but that separation also seems like a pity.

One of the many valuable aspects of my tenure at Rhizome was the fact that for more than three years I did the front-line tech-support for a website with more than 1 million pageviews a month. I learned first-hand how easy it is for non-technical users to find web sites difficult or frustrating or even intimidating. And when I rolled out a new change, I could tell within weeks—on the anecdotal level at least—whether it had made people’s lives easier or harder.

After all, who are you writing code for? If you’re writing it for yourself, then no worries. But plenty of us are trying to write it for others, whether those other people are fellow Rubyists or blog advertisers or hedge fund traders. Our profession has a terrible track record at understanding what others need out of the code we create. If you have ways to get closer to those other people, and to understand how to make their lives easier, then those ways are probably time well spent.

Two good responses to my recent post about Agile methodologies and vulnerability to lawsuits. Bill Anderson points out that Agile methodologies can be win-win: “Visible and confirmable system behavior might avoid mis-understandings about expectations for customers, users, and developers.” I agree, but I think increasing your odds of success might not mitigate a potentially bigger downside. What happens if your client’s internal contact leaves the company, and her replacement is much more antagonistic? What happens if your client is bought out by another company, and the new owners decide to run a stringent legal review of previous contracts? These are all remote possibilities, of course, but if a lawsuit is a possibility, they’re potentially disastrous scenarios. And it’s those remote possibilities that lead companies to add otherwise unnecessary safeguards—such as lots of fixed contracts and verbose documents.

Kris Johnson takes the opportunity to lament the arrogance of methodologists of all stripes:

Unfortunately, there are a lot of people out there who think they know the One True Way to develop all software, and promote a set of very-specific “best practices” that any True Professional must follow.

While I agree with this assessment, I’d also point out that having many methodologists can be a saving grace when it comes to litigation—as long as those methodologists don’t all agree. A lack of consensus might help in defending your own practices. The majority of software vendors might rely on heavy documents and static processes, but the agile minority is healthy, vocal, and has big success stories under its belt.

Diversity of opinion is a valuable thing: This is worth keeping in mind when programmers argue for stronger professional organizations as a way to elevate the craft. At a certain point, such organizations reinforce their idea of professionalism not just positively, but negatively, by explicitly working against those who practice in unapproved ways. The American Medical Association, for example, once lobbied against both chiropractors and acupuncturists.

Ultimately, most of the people involved—even, I’ll allow, some of the lawyers—are motivated by a decent goal: Software should be more reliable, and it should cost less. But short of punishing gross negligence and deception, I don’t know what good it does to involve lawyers and judges. There are lots of problems in the world. Most of them can’t be solved in a court of law.

Japanese blogger Hirano posts a chart mapping which skills Japanese IT workers have acquired, and which skills they want to acquire. Not being able to read the study that this chart is based on, I can’t tell how much it attempts to overcome the fuzziness inherent in its questions. (Does it make sense to ask a tech worker if he has or hasn’t acquired the skill “Linux” or “Security”?) Still, the general arc of technologies seems intuitively right, and it’s fairly provocative.

I got this via Tim Bray, who says he’s not certain what it means. Personally, I wonder if such a trend is specific to the technology field, or is just a more general trend you’d see in any quickly changing field with highly skilled labor. If you mapped this out for financial services, would you get the same trend, with hedge funds in the top-left quadrant and corporate auditing in the lower-left quadrant?

One interesting way to look at the chart is to note how quickly a skill moves from being cutting edge to old-fashioned. COBOL and Mainframe skills would’ve qualified as an “Emerging Skill” only a few decades ago. And if anything, such rate of change is accelerating—meaning that a college graduate today who banks his career on, say, Web Services, will face a severe skills obsolescence in his working life.

None of this is new, but I feel like the tech industry, with its love of change and its optimistic view of the future, doesn’t talk about it much. I know from personal experience that this industry can still be fun after ten years. But what about twenty years? Thirty? Fifty?

I’ve met many veterans in the field who are successful and content, but I’ve met probably just as many who are fighting a constant war against burnout. In many ways it seems that long-term success depends on the ability to either become a manager or a consultant, specializing less in specific technologies and more in managing people, organizations, and processes. But some programmers can’t or won’t make that transition, and the field can be more difficult for them.

Me, I’m only a few years younger than the Unix epoch, and already I can feel myself getting curmudgeonly about the newest, shiniest toys. Take “Ajax”, for example: Since Adaptive Path coined this term in February, web programmers everywhere have been abuzz with discussions about its potential. I follow along with the discussion, particularly in cases where Ajax implementations are causing interesting conflicts with notions of RESTfulness, but I may never program a single line of Asynchronous JavaScript + XML myself. Not because I think Ajax isn’t interesting and potentially lucrative. But because the idea of learning how to jump this particular technical hoop strikes me as just too much work. Leave that stuff to some eager 21-year-old. I’ve got other things on my mind.