29 January 04 - 14:34Documentation: managing your manager

In a newsgroup recently, the question came up: "What to do if my project manager says we're not writing enough documentation ?"

As with many such questions, the issue is less one of documentation per se, and more to do with managing your manager. Here are some tips which have been found to work, depending on the situation, but may well be inapplicable to yours.

Tell your project manager that his/her criticism is too brief to be useful, and not specific enough. Or...

Ask your project manager to write one example document which would satisfy him or her, so that you have at least an implied specification of what you're supposed to produce. Or...

Look at the list of outstanding defects, if you have one, and for each defect on the list trace it back to the missing page or paragraph of documentation which would have prevented that defect; write that. (If the defect could have been prevented by writing a test case, do that instead.) If you have no defects that can be traced back to missing documentation, don't write more documents than you already do. Or...

Trawl the corporate Intranet for old design documents; cut page-sized bits from these and paste them together behind a cover page to yield a "new" document as large as necessary. Give your project manager those, he/she wasn't going to read them anyway. Or...

Only in the last resort should you inflict bodily harm on the project manager. Like cats, they cannot be trained by negative reinforcement.

- Software Development - three comments / No trackbacks - § ¶

26 January 04 - 17:26The team-building lunch

When I listed my criteria for good teammates, I included "will have lunch with me on a regular basis". That seems to have surprised some of my readers, to say nothing of those who were apparently angered.

There must be food - I first came across that bit of advice on Ward's Wiki, and it has helped me in many different situations. Whenever I run a half-day training session, I buy snacks for the trainees. At conferences, I've noticed that the best place to strike up a conversation is often the food queue. And it's over lunch that I learned the most useful things about teams I've worked with or consulted to.

For me, what happens at lunch has always been an index into the health of a team, and its relation to the rest of the business. Primarily, I find that if I'm excluded from lunch most times, that's a good clue that I'm not fitting in very well with the team; but there are other clues. Do the developers always stick together, never to be found at the same table as the people in sales ? Is everyone having lunch by him or herself, in particular buying cheap sandwiches and eating at their desks ? Is there a huge contrast between the manager's lunch and the rest of the employees ? Are people very set in their ways, always eating in the same places and with the same tablefellows, or do they value variety ?

Moreover, people need a time and place where they can discuss things other than work, if that's what they like. Lunch is good for that. And for those people who are usually hard to shut up, it ensures there is a time when their mouth is otherwise engaged; that can be priceless. How else are you going to turn a talker into a listener ?

- Private Life Of The Brain - three comments / No trackbacks - § ¶

22 January 04 - 10:48Blogging for one year

Today marks the beginning of my second year as a blogger. One year ago I wrote: "The idea is to put at least one fresh thought down every day. We'll see how that goes."

I don't know about freshness, but this blog has 167 entries. The average therefore comes out to a little under half a thought per day, which isn't so bad.

- Blogversations - No comments / No trackbacks - § ¶

20 January 04 - 00:45What failed teams have in common

The Despair, Inc. poster has it right - I've been on disappointing teams in the past, and the one person they had in common was me.

Someone asked recently, Are you the kind of person you'd want to be on a team with ? Yes, I answered tentatively; I don't think of myself as a Lone Ranger. Reality might well not agree with my self-image. There's one particular team I've been on for the past fourteen years - I get the occasional complaint, though I think I'm improving.

I'm working out a "laundry list" of qualities I want in someone who's on a team with me. They are tempered by checking, in each case, that they are qualities I think I possess.

This is what I've been able to come up with so far:

• is enthusiastic about the work (at least some of the time)


• doesn't yell or get angry (most of the time)


• doesn't make fun of me (at inappropriate moments)


• is willing to have conversations about my ideas


• has and shares ideas (especially when I don't)


• will have lunch with me (most days, when possible)


• bathes or showers daily

What would you add ?

- Management - six comments / No trackbacks - § ¶

18 January 04 - 23:43Clean code isn't my job

I had an interesting conversation over a French-language programming newsgroup the other day. This person was inquiring about "Edit and Continue", tool support which would let him do simple, one-line changes to his C/C++ system from within a debugger session, and have the new code execute without needing to exit the program, recompile, rebuild, and start his session all over again.

My suggestion was to write small test programs to test bits of the program in isolation, which would obviate the need for debugger sessions as well as lengthy recompile/rebuild cycles. But, said my interlocutor, the programs I work on are "plugins" which fit within a larger architecture; I have to load the whole thing before I can test my own code. Even better, I replied. There should be a clean and well-defined interface between plugins and core, which will assist you in writing drivers and stubs enabling the above strategy. No, he told me, the "plugin architecture" mostly exists on paper. The program is actually a mess of tightly coupled spaghetti code. At which point I suggested that maybe that should be remedied.

Now, and this is where this becomes interesting, my interlocutor said in any case his job wasn't programming. He is a PhD student, working on a thesis in geology, which just happens to depend on that system somehow. His job isn't to improve the code, nor does he have any say in how the code is developed; he has to take it as he found it. He said, and I quote (modulo translation) verbatim: "Me just PhD student, me do whatever thesis advisor says."

I wonder, in how many research labs around the world, in how many areas of science, is this scene being played out right now ? Is that something which has changed - i.e., is that a trend - and if so, is that cause for concern ?

- The Universe And Everything - three comments / No trackbacks - § ¶

13 January 04 - 23:40Misfits, or, there's no such thing as a requirement

Johanna argues that "Users can't know their requirements early", and illustrates with a simple but illuminating story.

The term "requirements" seems to be part of our final vocabulary - we assume there's such a thing as "what the system should do" (irrespective of whether the customers know or don't know what the system should do). We don't really question the deeper reasons why requirements should change over time, or change when users are exposed to the system; we acknowledge these as annoyances or hindrances in efforts which would otherwise be straightforward.

In Notes on the synthesis of form, buildings-architect Christopher Alexander discusses the design process in terms of "misfits". Design, says Alexander, is a matter of harmony, of good fit, between a form (what is being designed) and a context (where we use the thing being designed). A misfit occurs when some aspect of the form clashes with some aspect of the context. Instead of "requirements", we might use the term "misfits". In Johanna's story, we have a context - lodgings away from artificial illumination, thus subject to the natural diurnal cycle; and a form - the house itself, with its various devices including artificial lights. Good candidate misifts in Johanna's story are wasteful use of electricity in daylight, risk of accident when coming home to a dark entryway, needless effort in resetting the timer.

What misfits buy us is a way of looking at the design process which doesn't require sorting "functional" from "non-functional" requirements, explains why requirements change over time and explains why a stable solution is nevertheless eventually produced.

Consider simple problems, say ones involving a handful of what Alexander calls "misfit variables". Take the design of a wrench, for instance. The goal is to adjust all of these variables in the object being designed so that there is a good fit between form (the object) and context (which includes when, where, how, who (etc.) is using the object). This is quite simple if the variables are independent. It gets more involved if the variables are related to each other: say, the length of a wrench handle relates to the "excessive cost of materials" misfit, but it also relates to the "insufficient torque" misfit, and in the other direction to the "risk of stripping bolt corners" misfit.

Design becomes hard when adjusting one misfit variable in the "right" direction causes another misfit. With these complex problems, the interrelations between misfit variables make it impossible to compute an "optimal" solution in any feasible amount of time. The interrelations are such that any adjustment causes a "ripple effect" of misfit in other variables, which in turn affect other variables, etc. These ripple effects are the reason why users frequently change their minds about requirements after they've seen the software.

Alexander shows us how to take a step back from the detail of each misfit variable, and view the whole network of them. Design is a matter of partitioning this network so as to minimize "ripple effects". Notes describes one method of achieving this partitioning.

Alexander uses the same boolean networks, which he borrows from cyberneticist Ross Ashby, which were used later by complexity science theorist Stuart Kaufmann to illustrate "self-organization". (There's more than one interesting convergence here. Kaufmann in turn inspired the agile process Scrum. Alexander was also the inspiration for the design patterns movement, among which many are now agile proponents.) They draw different conclusions, but somewhat similar and compatible with each other.

Alexander shows that our preconceived notions of which misfits group logically together, and thus our breakdown of the design process into component efforts, have actually little to do with how the network "wants" to be carved up so that a stable solution emerges. On a related note, Kaufmann shows that whether the network of conflicting misfits eventually "settles down" to a fairly stable and ordered configuration is essentially a matter of how interconnected the variables are. Too much interconnection, and the network never stabilizes; too little, and no "interesting" form can arise.

The term "requirements" implies that there is a constancy to the various bits of "what the system must do", and that the bits don't interfere with each other. That's way too simple a picture.

- Software Development - No comments / No trackbacks - § ¶

10 January 04 - 22:53Models of stability ?

The previous entry on models of change reminded me of something. We devise models for what we want to explain. We want to explain what is not obvious. If we have models of change, it must be that change isn't obvious.

Yet change is just the flip side of stability - things change when they don't remain the same. (Mr de la Palisse would be proud.) Is it any more obvious why things remain the same ? To look for models of change, look for models of stability.

- The Universe And Everything - three comments / No trackbacks - § ¶

09 January 04 - 14:34Models of change

Here is a short list of models of how people, organizations, industries and societies change:

• Weinberg's "naive" models:
  • The diffusion model
  • The hole-in-the-floor model
  • The Newtonian model
  • The learning curve model
• Virginia Satir's change model
• Geoffrey Moore's "Crossing the chasm" technology adoption model
• Kuhn's model of paradigm shifts (as interpreted by Simsek) : "normalcy, confronting anomalies, crisis, selection, renewed normalcy"
• Ghandi's model: "First they ignore you, then they laugh at you, then they fight you, then you win."

Those are the models I know. Models I want to look into:

• Axelrod's "Engagement Paradigm" (this article also lists "naive" models)
• Jeanie Duck's "Change Curve"

P.S. Yes, I'm practicing my list-making skills.

- The Universe And Everything - two comments / No trackbacks - § ¶

08 January 04 - 16:56If design is the answer, what is the question ?

I've always liked Frank Patrick's take on project management: Frank asks, "If project management is the answer, what is it an answer to ? What is the question ?" And the question is - "What should I be working on ?"

Frank's concern with finding the appropriate question - not just the answer - stems, I think, from a frustration with discussions of the "how's" and "why's" of project management techniques - discussions which can easily lose sight of why our projects need managing in the first place. You may not agree that the above is the question which project management needs to answer. But knowing what question needs answering focuses your search for answers.

We could take the same tack with respect to issues of software design. After following endless discussions on aspects of software design ranging from "Is it actually the case that coupling is bad and cohesion is good" to "Is all duplication actually bad" to "How should one represent association, composition and aggregation" - it is a good thing to come up for air once in a while and ask, What is the question ? Good design principles in software are the answer, but the answer to what ?

I'm not going to answer that today.

- Software Development - No comments / No trackbacks - § ¶

08 January 04 - 16:17Project Management, the Movie : the Article

As I noted in "Blog to print", I have an article out in the December issue of Cutter IT Journal which grew out of a previous entry here.

I'm in good company - the issue, edited by Lynne Nix, has articles by Eileen Strider, Mark Keil, Payson Hall and Capers Jones.

- The Universe And Everything - one comment / No trackbacks - § ¶

07 January 04 - 17:32The Paradox of Articulation

Think of the process you undergo when you write e-mail for instance. You write something, which you intend to express your thought. The act of writing brings the realization "No, this is not quite what I wanted to say". So you revise and alter. But after a number of drafts the pressure mounts : "OK, enough dithering, this is what I wanted to say". You have lost track of the inarticulate thought under all the expression, so you no longer want to revise or change the expressed thought.

It is the same with "process" : while not written down (inarticulate) it can not be tested, verified, probed for correctness or fitness to purpose. I believe that this is the underlying reason people declare themselves "against process" - they anticipate and fear the unending journey of self-examination that articulation leads to.

As soon as the process is written down - articulated - it becomes false to fact, false to what we really do. And it becomes the crux of a complex balancing act of forces : - the energy invested in articulation drives us to say "This is good enough, accept it as written (with some exceptions)" - the mismatch between articulation and reality drives us to say "This is false and needs revision (to account for exceptions)" - the emerging elegance of our articulation drives us to say "This is true and nothing else exists (no exceptions)".

Also, if we feel more comfortable in the act of articulation than in performing the work itself, we may want to keep articulating for much longer than is reasonable, and eventually get disconnected from reality; we anticipate and fear the pain of confronting our articulation with reality. I think this is the trap that the "defined process" people fall into.

At some point the cycle begins anew - you find yourself doing or thinking something that requires articulation again, because you feel (inarticulately) that it is quite unlike what you have articulated so far.

N.B. this is verbatim a rather old post of mine to the Systems Thinkers mailing list. I'm putting it up here as a first or even a zeroth draft - I want it somewhere I can look at it. Later, perhaps, I'll polish, revise, clarify.

- Private Life Of The Brain - one comment / No trackbacks - § ¶

04 January 04 - 13:35New Agile blog

Joseph Pelrine (Smalltalker, XP veteran, and ScrumMaster) has just entered the blogosphere. Welcome, Joseph !

- Blogversations - No comments / No trackbacks - § ¶

02 January 04 - 16:21What the customer wants

Regarding the matter of a project's "requirements", many people will tell you that your customers don't know what they want. Just as many will tell you that customers do know what they want. Neither branch of this dichotomy is useful.

I'm always put off by the suggestion that "customers don't know what they want", or that they "know what they want but not what they need", and that it falls to someone on the project team to divine the requirements. (I've heard this asserted seriously.) On the other hand, I've also heard something along the lines of "if we do whatever the requirements say, at least someone else will be to blame when the software turns out to be useless". Too many teams expect that the requirements will be handed to them on a silver platter.

When I entered the field about 15 years ago (counting from the first few occasions someone asked me to solve a problem of theirs by writing software), I believed in "customers don't know what they want". I knew better than my customers what they needed. One sentence of customers' requirements was enough for me to generate volumes of source code, or pages of product specification. I preferred the former, and grew cynical about the latter.

Later on, I started to insist that customers should know what they want. Work would not start until I was handed a complete product specification. If anything in there was incorrect, it was someone else's problem. On several occasions I invested a lot of effort in tracing a bug back to someone's incorrect spec, so that I could come back with "I did just what you asked for, and that turned out to be a terrible idea".

Not only am I familiar with both attitudes from personal experience - I went back and forth from one to the other over the course of my career, and it's likely that I occasionally exhibited both on the same project. I'm not a bad person, so I suspect there was a sensible reason for both attitudes. If I had to name it, I would say that both attitudes ensured I could do my work with a minimum of contact with the customer. (Working with computers has always been a lot simpler than working with people.)

The most important thing I learned in 15 years could well be the realization that solving someone's problem with code involves listening to that person.

Nowadays, I expect the people whose problem I am solving by writing code to be articulate, and to have something to say about the problem. My own responsibility is to ascertain how code will help solve the problem. We (my customers and myself) are exploring the problem; that is a joint responsibility. What the customer wants, primarily, is for me to help as best I can.

- Software Development - No comments / No trackbacks - § ¶

01 January 04 - 20:52Holiday waste

Do you know anyone who will be in the office tomorrow ? Who was in the office yesterday ?

I wrote "anyone who went to work" initially, and went back to correct that. Just because you're in the office doesn't mean you're doing any work. In particular, if you're in the office on a day where just about everyone else is away on vacation, and watching the clock until it's time to take off for the New Year's Eve party, it's a good bet that you won't be doing much productive work.

Now, that's fine if you're manning the phones, watching a closed circuit TV monitor, or otherwise in a profession where your presence is intrisically valued rather than your activity, but that's not the case in the software development business. Developing software is a creative activity, which is performed collectively and requires motivation and coordination in equal measures.

Looking back, though, I can remember many occasions when, on the eve of a major holiday (Christmas, New Year, May 1st and August 15th are the main such occasions in France) I dutifully turned up at an otherwise deserted office to spend most of the day twiddling my thumbs, or sometimes chat with the one other colleague there.

I've often wondered why none of my employers had the idea of just closing for that day. There's absolutely no incentive to use up a day's vacation in such situations. If you're not going away for Xmas, it's usually because you're saving it up for some other period (or have already used up your vacation, though that tends to be much more rare in this business). The salaries will be wasted anyway, so why not give everyone a day off, or maybe offer people to stay home at half pay ?

- Management - one comment / No trackbacks - § ¶