From this table (which has been a regular slide in our Agile in Action roadshow series) we see that tools can help, in this example just over 40 hours/iteration, which if you break that down further works out to about 1/2 day per developer every 2 weeks. Now that is an ROI that an agile development team can relate to…

Documentation is the castor oil of programming. The managers know it must be good, because programmers hate it so much. Gerald M. Weinberg

I used to be a strong believer in formal doc reviews. Distribute a draft, plan a meeting, and have everyone gather around the table. But in the last few years, my team has moved towards mostly meetingless reviews–because people hate review meetings (you know, like code reviews, only worse), because people haven’t always read the drafts when they get to the meeting, and because some of our dev team is overseas.

• First, we distributed PDFs and asked reviewers to submit comments in email or on a hard copy. For the overseas team, email was the only option. This is not fun for either the reviewer, who has to do a lot of copying and pasting and referring to page numbers, or for the writer.
• Then we tried Adobe Acrobat PDF reviews, which allowed all reviewers to comment on the same PDF and view others’ comments. This was a big improvement over the email method.
• Now that all of our product documentation is hosted on a MediaWiki-based site, we’ve asked reviewers to edit the pages themselves, or add comments to the Talk pages. This makes life much easier for both reviewers and writers.

Still, as Anne Gentle stresses in Conversation and Community, using a collaborative medium doesn’t guarantee that collaboration will happen.

How do we encourage developers and testers to “own” the documentation for their tools, and to think of help as part of the product? If we can get developers and testers to RTFM, the benefits are obvious. They understand the tools in a way that no one else does, so they’ll provide feedback that no one else can. And they’ll become familiar with the help for the tools they’re responsible for, so they’d know whether a change they’re making or testing would affect the help.

I thought up a few ways that might increase the amount of review feedback:

• Create review tasks in our Agile project tracking tool, XPlanner. A top-down approach, and I wasn’t enthusiastic about it. Kinda like the daily castor oil treatment.
• Make everyone’s MediaWiki user page into their doc review page; we’d add links to these pages and reviewers would be notified through email, then they could delete the link when they’ve reviewed it. A nice bottom-up approach, I thought, in the spirit of the wiki.

But encouraging collaboration may be less about tools and more about process. If we involve reviewers earlier, they can tell us what they think before we’ve written a draft. A draft takes a long time to review, and if a reviewer doesn’t like it, they might not provide any feedback at all.

As Donna L. Davis says in a review of Andreas Rüping’s Agile Documentation:

Documentation isn’t bad. But bad documentation is terrible.

Is reviewing docs worse than eating Brussels sprouts? Do you review docs when asked, or do you hide the invitations under the edge of your plate, hoping mom won’t notice? Is the help so bad that you can’t be bothered? Are you just too busy? Are you one of those people who never consults the help for tools you use? Do you think your users will be able to use the tools you’re developing or testing without the docs?

What would make you more inclined to “own” the help for the tools you’re developing or testing?

• Organizations (and individuals) are begging for as much information and guidance as they can get on Agile and tools for Agile, and are willing to give up a days in the office and brave horrific traffic to get it
• Teams that are 6 to 9 months practicing Agile think they’re novices, but in reality are seasoned veterans and have lived through most of the nightmares newer teams are currently facing
• Toronto cab drivers have a random-number generator for their “flat-rate” fares from the airport
• The majority of our audience would rank low to medium on both their knowledge and their adoption of Agile…they all want to go Agile, they just don’t know where to start (or if they were started, how they could improve things)
• Window seats suck, but not as much as middle seats
• Developers do code reviews, but don’t like doing them…
• …but you could always count of the one guy in the audience who claimed to like them…obviously someone’s living in denial
• And finally, if you are in 3 different hotels in 3 nights, keep the sleeve your room key comes in on you at all times…I guarantee you’ll forget your room number at least once during the trip.

Vim isn’t an editor designed to hold its users’ hands. It is a tool, the use of which must be learned.

Later, someone sent me this beauty, from Elitist Jerks:

Stop being lazy and read.

Are users lazy? Do they expect hand-holding? Do they expect one button and no manual?

Or is this more true to life?

In the end, it probably comes down to this: Make tools usable. Then technical communicators can spend more time creating truly helpful help, and less time explaining a bad UI.

If our goal as communicators is not just great help, but a great product, Agile makes more sense than ever.  If we want our usability suggestions to be implemented, we need to get developers’ attention while they’re working on that feature. Find the rough edges that would require a lot of splainy-splainy, request a change, and then rejoice that we don’t need to explain what’s now obvious. Sometimes it’s hard for me to decide what’s a rough edge. Would my audience of developers find this as confusing as I do? But I’m learning to trust my gut.

At the same time, though I appreciate the benefits of Agile, I’ve started to worry less about the help being “done” at the end of an iteration; instead, I want to make sure I understand a feature well enough before the end of the iteration to suggest design changes and know what help will be required.

If adoption of Agile is impeded by its very nature in large organizations and Kanban is the proposed answer, then the Agile solution is insufficient. Agile needs to expand its scope to be relevant and useful for non-developers as well as across development teams.

To understand how Lean applies to Agile development, I’m going to take a short detour though history.

Mapping manufacturing principles to software development is an interesting cross-pollination of ideas. Discrete manufacturing is quite different from application development, but that doesn’t mean the software industry can’t learn a thing or two from a different sector.

Lean was born out of a need to re-invent the manufacturing industry, which had not really evolved since the inventions of Henry Ford and the production line. From Ford’s time to the post second world war period, most manufacturing was very good at making enormous quantities of the same product, regardless of the demand. Ford’s famous quote about color clearly exemplified the thinking of the day: “Any customer can have a car painted any colour that he wants so long as it is black”. In other words, Ford’s production line was optimized for manufacturing, not profit, and turned out to be quite inflexible when market conditions changed.

In the 1950s, Sakichi Toyoda made a revolutionary leap forward with two principles:

1. Pull vs. push – at any point in the production process, the trigger to start work on a production unit is governed by its upstream neighbor.  As an example, I do not start my work on a product unit until the guy following me says he will be able to receive it.
2. Efficient manufacturing depends on the management of three key inefficiencies: overburden (muri), inconsistency (mura), and eliminating waste (muda).

Together, these elements formed the underlying principles that Sakichi spearheaded into what is now known as The Toyota Production System (TPS). The TPS has subsequently been used as the the basis for Western derivatives such as Just-In-Time, value-stream mapping, Six Sigma and Lean, to name a few.

So what does this have to do with Agile and large organizations?

There are well-documented cases where agile alone was not enough, and that’s where Lean/TPS can add value.  For the most part though, the application of Lean principles has been limited to just one part: Kanban.

The TPS Kanban methodology has two aspects. First,  a Kanban card is attached to every unit under production and carries contextual information (metadata) about the tasks that need to be performed on that unit  and second, task readiness and data are used to trigger an specific action (work).

Over the past decade, the Agile methodology has been used successfully within  development teams, usually sized between  8 and 15 people. Agile’s benefits and values for this type of environment have been well articulated by many others (including on this blog), but most Agile adopters may not have realized the close mapping to Lean/TPS.

• Muri (overburden) – overproduction – in an Agile context, this is usually expressed as over-planning
• Mura (inconsistency) - elimination of bugs at the earliest stages, resulting in more  stable and reliable iterations
• Muda (waste) – close interaction with the customer to absorb change and prevent wasted iterations
• Kaizen (continuous improvement) – refactoring, unit testing, system integration

Secondly and more importantly for large teams, the TPS/Lean idea of pull vs. push is key. But there are other aspects of Lean/TPS that would benefit software development, Kanban being an important one but not the only one.

In an Agile context, Kanban is usually expressed as a board or wall with movable index cards to visualize units of customer value and work flow. This is where I think the rails have come off Agile/Kanban compared to the original TPS philosophy.  Kanban is just one gear in the whole TPS methodology.  Its an integral part but no more important than the other parts.  To function optimally, the TPS/Lean requires all the piece to be implemented not just one.

The other aspects of TPS/Lean are:

• Andon (signage, early warning)  - literally means paper lantern and is used to call attention to a problem in the process.  For Agile, it should be express as how do you measure your team’s progress and convey that information to the whole organization.
• Jidoka (autonomation) – automation with human intelligence.  The efficient use of tools like static analysis and continuous build to aid in development.
• Poka-yoke (fail-safing) – not just exception handling, but actual prevention of faults and counter-measure strategies to prevent the fault from reoccurring.

These other parts of the TPS were not born because people like more processes and rules; they came out of need, something the agile methodology has yet to realize it requires.

In preceding posts on this topic, I’ve outlined the continuing shift from in-person, physical interactions as being the defining notion of both social and business contexts, towards virtual interactions and marketplaces, and the fact that in all aspects except the most personal the latter can fulfill everything expected of the former. But what does all this have to do with engendering a vibrant and successful code review practice within a development organization? On the face of it, nothing much. Code review, you could determine, tends to happen within organizations that enforce it, so all we need to do is to pass a rule requiring code review before shipment and we’re gold, right? I mean, what could go wrong?

Unfortunately the reality isn’t so clear cut. Most organizations worth their salt have a “requirement” for code review to be performed. At least on the important bits (a definition I particularly like, particularly when it comes to motivating programmers working on the “unimportant” bits). Or the hard bits (likewise). One awesome process description I saw in action recently called for the architects in the team to review each others’ code, but everybody else got a free ride – because obviously the code that our highest paid, most talented developers produce is the stuff we’re really worried about being wrong, amirite?

Despite such requirements, whether they make sense or not, the rarity of code review is out there for all to see. In fact, we recently sponsored the analysts at Forrester to produce a survey of code review practice in various different development environments (embedded, ISV, IT, etc.) and found that although most developers appear to believe that they live in organizations that do code review, most also claim that it doesn’t happen consistently for some reason or other.

Let’s take the most prevalent excuse claimed: too busy, got other stuff to do. Why is this claimed so uniformly? Certainly developers are busy people – we pay them a lot and expect a lot for that remuneration, after all, so sure they’ve got other stuff to do. But if we put this in another context, perhaps outside of the development process, say visiting Grandma, I’m sure there’s a parallel to be drawn. After all, we should definitely go visit Grandma more often. She’s probably not going to be around that long. She’s a nice lady, and she cooks cute little cupcakes when we do go there. So why not do it more often? Too busy, got other stuff to do. And, of course, it’s really annoying to drop whatever you are legitimately doing (whether development or otherwise) and go visit the old lady with the bad habit of talking about you as if you weren’t in the room.

As a manager, therefore, your task in ensuring code review has a much lower friction profile to it, is to remove what I think I’ll try to trademark as The Grandma Effect. If I have to stop what I’m doing, put on my Sunday best, and sit listening to stories from three decades past, I’m going to find all kinds of reasons not to. But if instead (to stretch the analogy to what I’m sure is the breaking point), Grandma were to learn how to play a wtf-pwning Mutilate-spec’d Rogue, then my interactions with her become much more palatable and manageable. Replace the trip to Grandma’s house with the annoyance of setting up a formal code review and you’ll get the picture.

There’s a tipping point here, and it revolves around the place and relevance of social tooling within your development team. You, your peers and your reports are currently interacting with friends over MSN, Twitter, Facebook, you name it. They’re booking dates, arranging weekend schedules, and getting the latest news from Reddit. You name it, they’re doing it and it’s all coming to them through a few pretty simple to leverage mechanisms.

Replace their social and common knowledge-gathering activities with knowledge leveraged within the code base, and it’s pretty easy to see how you could graft what has the potential to be a very annoying activity, e.g. code review, onto a natural way of conducting business. Instead of creating an entire workflow around the invite, simply inform interested parties about commits and let them decide whether to review or not. Instead of insisting on top-down imposition, encourage a bottom-up adoption simply through ubiquitous availability of information.

Nobody forces anybody to use a service like Reddit, after all. It exists and thrives because of the community that finds value in its presence. Personally I interact with it through RSS as I find that the most natural way of learning what it’s got to say. Lots of different feeds of information for the different types of news, all presented through a common aggregation mechanism that feels natural, that works well, and that I don’t have to think about.

So, if commits that my team members are making, or commits that others are making to a component for which I feel either moral or actual responsibility are available through that same mechanism, I’m going to take advantage of the tools to review those commits and to make my presence felt.

No formal review.

No formal sign-off.

But also a guarantee of way more participation, and what’s more, a broad reach around the typical chain-of-command style code reviews that we know and hate, instead engaging atypical contributors, not to mention the legion of lurkers just out to learn more. And isn’t that what it’s all about at the end of the day?

In summary: don’t require the architect, but appreciate their presence. And instead of bringing the people to the code, bring the code to the people.

But here is where there is just a massive difference between Waterfall versus Agile.  By far the biggest lesson for me and why I love Agile is all based on visibility.  Having a working product in one simple iteration means the world.  So even though I was ranting in my previous post, imagine if we were doing waterfall.  Chaos could have ensued once the product was integrated (maybe months after).  As many point out, iterative development shows us up front (in two weeks or less) that we have a major problem.  I’ll stick to Agile, thank you.

So Agile is great, I’m all aboard but I still have to do something about working remotely.  Once I get this addressed I should be sailing.

I’ve come across a few things that people are doing .  Mostly with some interesting video conferencing techniques (here and here).  Do these really work?  There are some studies which are interesting but they are not really applied in an Agile context.  I did come across one article that might be helpful…although I need to shell out a few bucks.  I did find one reference on martinfowler.com that I thought was useful as it goes through the key points you need to consider with offshore development.

Overall, I still don’t have a good plan to deal with this.  So let me ask everyone out there, please let me know if you know of any good references.  I could certainly use some help.

Klocwork recently commissioned a survey conducted by Forrester research on this whole topic and the results are pretty interesting. While there’s a whole bunch of data that can’t be covered in a single blog post, a general theme we found is that developers see the value of code reviews, they’re often mandatory, but the process itself seems to be ad-hoc and quite ‘behind the times’. Here’s an example of what I mean:

Code Reviews - Mandatory but Ad-Hoc

So, code reviews are mandatory but you can kinda invite whoever you want to review the code. Shouldn’t who reviews the code be pretty important? (Hint: Yes)

We’re gonna keep talking about different aspects of this important development milestone, so stay tuned and we’d be interested to hear anything you have to say on the topic.

Being a product manager, one of the things that is really ringing true to me is where Agile falls flat–working remotely.  Lots of discussions on how much it can suck here, here, here and here.  As part of my job, I travel… lots.  If I’m not at a customer meeting I’m at the next trade show.  This means many design and planning meetings are done remotely.  I end up finding we have developed something different than what was originally discussed or at least what I thought.

This gets frustrating because it has a major impact — all of a sudden as opposed to having that working functionality at the end of the iteration, you are set back by redoing that same work the very next iteration.  About as productive as watching every single sport of the Winter Olympics (I don’t even like figure skating…I swear).

As much as I’m puking all over Agile, I’m still very invested (messy as it is).  Let’s face it, offshore development is a way of life and there are many things people are using to work in this remote context.  Next week I’ll post the opposite side of things and discuss the consequences of working remotely along with the value Agile does give you.

Okay, so why do I think the Everything is big in Texas is accurate. For starters, my big delay is due to a big thunderstorm. My rental car preference is a Compact car, and what do I get? A Yukon…I’m not sure what is bigger, this vehicle, or the Canadian Territory with the same name.

I saw big hair, big hats, big rings, big belt buckles, big omelets, big waffles, and big enchiladas. What I also saw was a big enthusiasm for Agile development. We had a great turnout that was fully engaged from the instant the roadshow began, asking questions wanting to know more, sharing their experiences with others, visiting with the vendors and not leaving until they got the information they needed. I wrote a few weeks ago about Agile adoption and where it currently was, and participating in this event, and speaking with the attendees, it allowed me to gain some additional data points that only strengthened my beliefs on this…Agile is definitely growing, and in all industries. As I said before, I truly believe almost all organizations have some Agile developments teams.

Hopefully the enthusiasm I encountered in Dallas will follow us to Washington D.C. And I’m thinking I may want to introduce myself as Todd Ovechkin…

When you think of a social activity, what do you think of? Perhaps a rave? Or maybe a quiet bridge foursome is more your style? Or even a Matrix-style meet-and-greet complete with latex and contortionists? Ahem…

Or maybe you’ve finally let go of this old-world requirement to actually be in the presence of an individual to enjoy a social encounter with them, and instead have embraced the reality of the 21^st century, that society and social interactions no longer require physical presence, and instead surround us every day, at every minute, as long as we (virtually) get out there and find them. Speaking as a long-time online gamer, I have a circle of folks I consider friends, with whom I talk most evenings, with whom I’ve spent quality time learning and beating goal-based activities, yet none of whom I’ve ever met. And whilst their reaction to some family tragedy on my part may result in no more than a weak “dude, that blows…” on some forum or other, in every other aspect of social interplay, they fulfill exactly the same role as those few- and far-between actual, you know, friends that each of us cling to throughout life.

According to a study on the topic conducted earlier this decade, friendship is becoming something of a luxury for the average American adult. Rather than expanding our circle of friends as travel has become more reachable for the masses, we’ve instead decreased that circle from an average of 3 to just above 1. So are we all just becoming obnoxious, introverted, “bah humbug!” Ebenezer Scrooge wannabes? Perhaps, and certainly that’s the trite response to the statistics for people in search of a quick buzzword or appliance to blame.

But perhaps instead of this reflecting a net diminution of our quality of life, we’re simply replacing much of what was considered necessary in previous generations (beer with the boys, poker night, ice fishing trips, whatever floats your boat) with a more constant, more consistent, but at the same time more arms length notion of friendship and social interaction. Though different, it fulfills everything we need in terms of communication and support, but leaves us free to concentrate on our family lives, or personal hobbies, or whatever else makes us happy to be, well, us.

Friendship when we want it, on our terms, and only then.

One potential projection of all of this can be found in the ongoing trending of the social nexus of life, business and relationships towards the online marketplaces that have sprung up around activity-, or focus-based requirements (I referred to this in my first post on this topic, drawing the correlation between Facebook and dating, LinkedIn and prospecting, etc.).

Find a marketplace, find a life (or maybe, a Second Life) – and frankly, is that really any different from the actual bricks-and-mortar reality of the rat-infested, smelly locales of the distant past (minus, you know, the scary crone shouting on the street corner, and the propensity for picking up the Black Death at a moment’s notice…)?

Indeed, my Chief Architect likes to describe an attendee at a recent conference as saying something like, “But what should we do about all these old people who can only e-mail or even worse need to use the phone? I mean, how am I supposed to communicate with somebody who doesn’t have a Facebook account, or doesn’t keep up with Twitter?” Note that this wasn’t a casual conversation over a beer, but rather a key point in a presentation (presumably to a room full of people with the requisite qualifications to be able to laugh affably at such an observation).

Whether we like it or not, whether we can personally deal with our relationships migrating into the ether, that’s where they’re headed, at double-quick time. So are you the guy with a red flag making sure that cars only drive at the same speed as horses, or are you busy building a Formula 1 car in your back yard?

And actually, perhaps more importantly, whether you’re either of these, you’d better believe your staff are busy climbing onboard with everything the new paradigm has to offer, so do you really want to be left playing catch up?

At a recent customer meeting I was surprised to hear that this highly compartmentalized, classified installation was putting a social media strategy in place (they termed it “our space”) to embrace what was happening anyway, and obviously to attempt to contain it within the security mechanisms required by their business. If they can do it, with all the restrictions and fenced-off classified strictures they have to deal with, why can’t we all?

Code review, you say? Social code review, more like. The current means of accomplishing the goal is fundamentally broken and will never scale, just like the requirement to only befriend people you could physically reach out and touch. The paradigm is changing, time to keep up…

And now in a deferential nod to the awesome Douglas Adams, this trilogy of posts on code review as a social activity will be continued in part IV, coming to a blog near you soon.

Don’t give up the big picture

Wouldn't it be great to use XPlanner for everything? Just imagine the velocity I could achieve.

When you work on a bunch of stories or tasks, it’s trees, trees, trees everywhere  you look and not a forest to be found.  This means that a nice concise how-to could be a long way off while you document myriad  features.

My advice is to finish the pieces and try to get to the minimalist documentation afterwards. In fact, Shannon Greywalker suggests going back and fixing things up later, but mentions that the business case for this can be a bit weak.  I think it’s worth the effort if you can swing it.

I’ve blogged before about how workflow can be helpful in getting the big picture. If the feature is big enough, workflow is your friend and can really pull you through.

Go for “What’s New” first
For each release, we document the cool new features on a “What’s New” page and “What’s New” is where I like to start.

If you can neither summarize nor explain why people would want to use a new feature, you have no business documenting it. “What’s New” keeps me focused on the whole point of the development work in the first place.

“XPlan” everything
I was a slow adopter of XPlanner, which is the tool our team uses to document development, testing and now, documentation.

Documentation has a separate project in XPlanner where we track our stories. At first, I found it difficult to update XPlanner regularly because some of our work can be difficult to account for.

For example, one our sales engineers is a prodigious reader of documentation who meanders over for his (thrice) daily “found a spelling mistake” or “did we document?” or “why can’t titles be printed on the PDFs generated by the wiki?” questions. All good points, with some requiring immediate action and others requiring medium and long-term planning.

But after reading Getting Things Done, I can really see XPlanner as a great life planning tool. See the screenshot above. For low self-esteem days, I recommend first completing tasks such as “Wake up”, “Shower” and “Eat breakfast” under the Personal Maintenance story.

Targeted procrastination
We’ve gone from blanket procrastination, which was a two-week offset, to carefully picking features that could benefit from a little more “fleshing out” before documentation. I like this approach because we show great planning with our procrastination.

For example, I like to spend bigger chunks of time on one thing, so I may delay documenting a bigger feature in favor of knocking some smaller stuff off the list one week, so I can string together several days in a row for the big stuff. I work better that way.

Ask a lot of questions
My modus operandi is asking as many questions as possible. Be annoying, but in a friendly and charming way. There’s an art to asking good questions, but sometimes it takes a bunch of stupid ones to get there. Dive in.

Secondly, the data supports the fact that people are adopting the aspects of Agile that work for them and there’s no monolithic Agile implementation approach, something that is consistent with the many Agile teams I’ve spoken to over the last 3 ½ years or so. I’d be curious to know how many teams out there are doing , say, Scrum “by the book”…if there is such a thing.

Finally, the other thing that the report hinted at, that I have seen firsthand, is that while most organizations are not completely Agile today, they almost all have some groups that are. I honestly believe that the percentage of organizations that have small pockets of groups doing Agile development is very high…perhaps in the 80s or 90s. I don’t have any hard data on this point, this is more of a gut-feel, but I would be interested to hear from our readers as to what they think.

Spend 80% of your time on One Thing.

As a manager of a small tech writing team in an agile environment (are there any large tech writing teams left out there?), it’s easy to lose myself in how-the-heck-can-we-keep-up-with-myriad-coders-frantically-coding thinking.

So when my manager scheduled a meeting to ask what innovations my team has planned for the next release or two, I thought of a few choice responses, such as “Um… how about documenting the new features in time for release? Is that innovative enough for ya?” and “Innovate THIS.”

Eventually I calmed down, since he’s the boss, and I have a mortgage.

I looked at the presentation I’d given after our last research period, that oh-so-short breathing time between releases. I reviewed the precious feedback we’ve gotten from a few customers and thought hard about it. I felt a bit better when I realized several of the goals we’d set for ourselves were already underway.

I dutifully wrote up a wiki page (because I can’t think without writing) that summarized a bunch of initiatives under each of our themes: process, community, quality, coverage, usability, and media. And I decided whether they’d fit into this release or the next. And I sent it off to my manager before our meeting.

He said OK, but where does all this get us?

He called my list depressing. Death by a thousand cuts.

He told me that to be successful, you need to put 80% of your time or money into one thing.

He suggested creating completely different help for just one tool. Throw out the old stuff and start over.

Once I played devil’s advocate for awhile, I began to see where he was going with this. I suggested a tool that I thought would be a good candidate. So I think we’ve picked our One Thing for this release.

Here’s how I’m thinking about our One Thing so far:

• Make sure everything the user needs to know is accessible from one place.
• Target two very different points of interacting with the help: the getting started phase and the troubleshooting phase.
• Use media that are best suited to the user and the information that needs to be conveyed.
• Make the help interesting, fun and effective. Grab and keep the user’s attention long enough to convey what needs to be understood. Defuse frustration.

And again (annoyingly), my manager is right; it’s much less daunting to try to make one thing better than to try to make everything better.

Now to persuade a few of the developers to star in our walk-through video….

OK, so Grease is really the word, but it didn’t fit my theme, gimme a break… Anyway, back on topic, since Joy of code review – part one of this series was published last year we’ve seen our new code review product in action in a variety of customer and prospect situations, and much like the eponymous hair product in the musical mentioned above, what we thought of as an interesting twist on an existing paradigm has turned into a bit of a barn burner. I refer, in this case, to the notion of what constitutes a code review if you remove the formalism of the invite from the process.

Consider what I’ll call, for the sake of being what marketers insist on terming “edgy” (for no really good reason as far as I can make out), old fashioned code reviews. You know the type, we talk about how we really should do more of them all the time. Check in your code, mail out a bunch of invites, mail some more when those get declined, gather around a table, project your code and wait for the insults to come rolling in.

You want to try that again, Mr. Coding Specialist...?

On the down side of these things are all the obvious problems… People don’t like getting reviewed, and unless you have a particularly unpleasant architect, the reviewer is no happier about being in the room than the person on the sharp end. Factor in the time, the annoyance of the arrangements, the opportunity cost of yanking the architect away from whatever they were previously doing, and you’ve got a really expensive, not very productive, but very important from a pointy-haired-manager-perspective process.

It’s really the classical no-win situation. Your manager requires it to be done. You hate it, and you know everybody else in the room hates it too. It’s like a giant dose of spinach to a five year old – doesn’t matter how good it is for you, you’d rather scream and sit in the naughty chair all day than let that stuff past your lips.

So when we were thinking about changing the approach to code review, it seemed obvious to us that whilst code review itself is valuable, the means by which it gets accomplished is fundamentally broken. Factor in peoples’ unthinking delight when confronted with anything social and what the heck, we figured, let’s turn the whole thing on its head. Instead of going top-down into a software organization and helping the manager enforce something unpleasant in an all new and collaborative-y, enterprise-y way, how about reaching out and encouraging bottom-up engagement through a model that people are comfortable with anyway, namely formless (a.k.a. social) communities.

Who’s the most obvious person to review the code of a good developer, after all? It might be their architect, but the chances of a good developer making a blunder of the architectural type (or any kind of dumb error) is probably reasonably low. Not saying it doesn’t happen, but we pay people at that level a good amount of money on the understanding that they produce decent code, so why then treat them like kids? Instead, if the code produced by that guy is made available for anybody to review, quite literally, then rather than getting the architect grumpy because he’d rather be thinking about the next huge money maker than what this guy happened to have done mostly right but nit-pickingly-wrong in this one situation, you get other team members taking part who have (in most cases) more useful input to impart anyway.

Instead of feedback of the “so… rather than using that particular transitive constructor, I’ve found that explicitly instantiating a new object and then initializing only what I need saves me, on average, 3 cycles a day” type, you might get the “hey, I was hacking on that a while back… might want to filter that data, cuz Bob’s front end passes in all kinds of crap… just saying” type instead – your choice, but personally I’d rather hear an hour’s worth of the latter than a moment’s worth of the former…

So who is at the review turns out to be much more important than whether it’s held, given some arbitrary set of “holding” conditions. But of course this comes with its own set of challenges, notably how do you know when you’re done if there’s no formal “meeting” to review your code (and to insult you, have we mentioned that part?).

In fact, it’s much like how the transition from waterfall to Agile was accompanied by many a gnashing of management gums and misplaced wails of “but how will I know if it’s going to be done on time?” But hey, that didn’t work out so bad, did it? People got used to time boxing, to changing requirement sets, to not waiting until it was arbitrarily “finished” and instead shipping it so as to gather feedback faster.

In my next post I’ll look at this new world order from the top down and examine the benefits to encouraging (rather than imposing) a social code review paradigm, and how it can make those metrics we know you care about look better than ever before.

The not-so-agile technical writer

I’m a technical writer who’s a big picture kind of person and that means agile development is sheer torture for me.

Going into my second agile project, I thought I would be able to go with the “flow” a bit more. I was wrong.

But, it’s important to point out that our documentation team hit all of our deadlines for new features, while substantially rewriting our help set and moving it to a wiki. I’m pleased with the outcome, but the trip was not pleasant.

This will be my first post in a series about technical writing in an agile environment. Today’s post outlines the obstacles that I face—aspects of being me (mostly). The next post will outline my coping mechanisms, as well as our team’s plan for our next project.

If there’s no follow-up post, that means that my unbridled honesty has gotten my keester kicked to the curb.

Waterfall nostalgia

I got started on this tech writing gig as a consultant. The product would be a month or two away from release, but mostly fleshed out and I’d swan in, grab the requirements documentation and the design specifications (sometimes I’d write those), play around with the tool and voilà: a manual. I could be very single minded about what I was writing and just get it done.

To be clear, I’m in no way saying that the waterfall method delivered better products or documentation, just that I had a better view of where we were going.

With agile, I feel like I’m jumping hither and yon doing all these minute tasks, with very little view of how they’re supposed to fit together. I’d often snarl to my manager after meetings that “I’m given a doorknob, a shingle and a shrub and told to go build a house with them.”

In fact, in his blog post about minimalist documentation and agile, Shannon Greywalker hits on my problem very accurately, and it’s this: “user stories are typically too granular” for minimalist documentation. Minimalist documentation, as he says, requires the “35,000 foot view”.

And what I want runs counter to the whole agile methodology: THE BIG PICTURE RIGHT NOW.

Multi-tasking versus uni-tasking

Another problem I face is that I’m a uni-tasker; I like to finish what I start—not doable when features span several development iterations and are in major flux.

There are blogs out there about what Generation Y is like, good or bad, but the one thing I do envy is their multi-tasking ability. These folks grew up doing homework, while downloading music and instant messaging their friends.

That’s the kind of splintered attention I envy. So, I got David Allen’s book, Getting Things Done, but I couldn’t finish it. I read the line about having “a mind like water” and then froze. Uh-oh. Mind like ice. When I think of my work and personal to-do lists, I’m paralyzed.

So, I signed up for meditation classes and I’m now making another attempt to read Getting Things Done. I’m hoping it’ll help me switch directions faster. Not easy when you feel like the Titanic and need an hour’s notice to hang left. Now that I think about it, the Titanic is a career-limiting metaphor.

Procrastination

Now it’s time for confession. Our documentation department fought for and won a two-week offset for our last two projects. Yep, that’s right, we trailed development by a two-week iteration.  It’s amazing that we haven’t been rounded up and thrown in agile jail.

By procrastinating this way, we hoped that features would be more fleshed out before we started writing about them. It was our vain hope that this would contain some of the rewriting efforts. We still did a lot of rewriting, but this round we were rewriting a lot of material for the wiki anyway, so the offset didn’t matter that much.

By now, you’re probably thinking that it must be very hard being me. Don’t cry for me, Costa Rica; I have ways of getting by. Tune in whenever the next post surfaces to find out how I cope and how I hope to improve.

The next 2 weeks were a roller coaster as we cut our teeth with Scrum. First the good:

• Communication: the interaction amongst the team members was definitely improved. If someone needed an answer to something, they immediately sought out help. The team realized that if they didn’t get timely answers, tasks wouldn’t get done. They really didn’t want to say those dreaded 2 words, “nothing finished”, in the daily scrum meeting.
• Meetings: The daily Scrum meetings were kept short and  sweet as everyone said what tasks they had finished, what they were working on, and if there were any roadblocks in the way. If something required further discussion, a break out meeting with the appropriate people was held.
• Energy: This was a high performing team to begin with, but there was now a newfound energy and buzz. This was a fun team to be around!

As the title suggests, there certainly was some bad in that first iteration.

• Testing and documentation: These were the 2 areas that struggled the most in the first iteration (and the next couple as well). They felt that their work was too heavily back loaded, that is, they would receive their stuff too late in the iteration to either test or document properly. Many of the stories were not totally Done because they were either not tested properly or documented with the time they were given.
• Defects and bugs: Because testing happened so late in the iteration, many of the bugs they found could not be addressed in that iteration. These bugs would have to be carried over to the next iteration, meaning the number of new stories would have to be reduced.

Now for the ugly.

• After just a day or so into the iteration, a plethora of unplanned tasks starting showing up on the Scrum board for many of the stories. These stories now had many new hours of tasks added to them, and we fell behind very quickly. This leads into the next ugly…
• The Burndown chart: Talk about a misnomer! We started to affectionately call our chart the burn-up chart, because there was very little down direction going on with it. Our chart would have looked great at a sales meeting, but in our Scrum meeting, not so much.

So as you can see our 1^st iteration had its share of warts, and in fact, the next couple did as well. But we didn’t get frustrated. We learned from our mistakes and changed/added things based on those mistakes. The Retrospective meetings were incredibly useful because they made us all take a hard, honest look at what went well, and what didn’t. The next, and last entry in my Going Agile series will look at the Retrospective meeting.

In our “team room” we had all the essentials in place for this meeting: stacks of color-coded cards (for capturing the various to do’s, or tasks), pens and highlighters, our Scrum board (with pins) to stick our tasks onto, and a keg of Red Bull, because we had no clue as to how long this meeting was going to last.

Everyone was anxious to get started, so I (as the Product Owner) introduced the first story that we were going to work on. I gave as much detail as I could about what the feature was, what it should do, the benefits the users would get from it, and so on. The team asked questions, and I answered them as best I could.

Once I was done talking, the most remarkable thing happened:  the team started to write down the various tasks required to complete the story. It started off quietly, as all the team members started writing on their cards, and to be honest, I was a little concerned that this was going to be the way this meeting would go. (Where’s the Red Bull, because this is shaping up to be a long and painful session.) But then the questions started coming from all sides –developers asking other developers questions, testers asking developers questions, documentation asking developers questions, developers asking testers questions, follow up questions, and so on. I vividly remember watching this, and the frenetic pace at which things were happening. I had worked with this team for a few years (doing Waterfall development), but I had never seen this level and intensity of communication and cooperation from the team. Once all the questions were asked (and answered), the task cards were collected and posted to our Scrum board. On to the next story, rinse and repeat…

The meeting lasted another few hours as we worked our way down the backlog and watched the new tasks go up on the Scrum board. By the end of the meeting, we were ready to start our Iteration. As the team left the room, they each moved a task from the “To Do” column to the ‘In Progress’ column, and the Iteration was underway.

It was truly incredible to see this team come together and work as a team so quickly, and to see how motivated they were to move to this new way of developing software. The next chapter in this series will look at the trials and tribulations of that first iteration.

As I mentioned earlier, this show is advertised as the only German-language conference around… and it was. So other than saying “hello”, “goodbye”, “thank you”, or “another beer please“, my German is, uhm, lacking. However, not a problem here; the Germans all speak very good English… which was a good thing since my presentation was in English. I had over 40 attendees at my session about how Source Code Analysis fits into Agile development environments, and it went very well. A number of attendees came to our booth after the talk to pick up our White Paper onstatic analysis and agile, and to get a demo of our latest release.

My two-week stint of planes, trains and automobiles continues tomorrow when I head up to Berlin for the weekend to see some good friends (and a football game in the Olympic Stadium), then it is back home on Monday. It has been a great couple of weeks in Europe, but I am looking forward to being back on good ole EST.

Back to the show. This is typically the IP Show, but this year is the first that ESC has been added to the agenda. I don’t think it helped attendance-wise. From what I can tell, there are maybe 200-250 attendees in total. I spent the last couple of days sharing booth duty with our friends from Emenda, France. Today, I spoke about how source code analysis fits into Agile development teams. I had about 15 attendees, which by all accounts was a good turnout.

I was able to cram about 40 minutes of material into 20-minute slot, and even had time left over to answer a few questions. Unfortunately, this show did not allow Exhibitors to attend any of the sessions. Too bad really, I was hoping to attend a few of them.

Next week, I am off to a similar show in Stuttgart, Germany, where I will have more time to present. Check back here next week for a recap of that event.

Since the launch of the seminal “Joy” work which hopefully doesn’t need mention here, we’ve seen everything from The Joy of Cooking to The Joy of Not Working (my personal favorite!), and so further to that deeply mined vein of authoritative works we bring you the necessarily over burdened… Joy of Code Review!

Joy, you say? Let me count the ways…

• I implement a task, using what I consider to be best practice patterns and guidelines; I slave over this, my creation, and when it’s done, I stand back and admire, much in the tone of an old master, this latest image of my greatness.
• Then I remember I need to get it reviewed…
• So, I timidly invite my Architect and 3 of his best friends to the war room to review my new baby
• After many rescheduling pauses, we finally gather…
• I hold my breath, turn on the projector, and bare my soul to the collective seniors in attendance
• 30 minutes later, having endured a ritual mind flaying, and the predictable but nevertheless enjoyable tortured examination of my parentage, education, upbringing and such fun rhetorical musings as “why do they let people like you graduate?” I slink out
• Follow up is, if anything, more painful as I’m reminded moment-by-moment of just how badly I’ve lived up to the expectations laid out for me by the senior team members

Anyway, so code reviews suck, amirite? But we all know we need to do them. Of course, we all know we need to do them for completely different reasons from each other…

• Kids right out of grad school know they need to do code reviews because although their code is, like, totally perfect, it’ll be good to show the old dudes their skillz, and for the old dudes to check out some rad new stuff that they might have missed along the way.
• Senior guys know they need to do code review because otherwise all kinds of terrible cruft will get promoted into the head branch and somebody (are you looking at me??) will have to fix it…
• Managers know they need to do code reviews because they read all about them in a book with a cool cover, and it’s all Agile and stuff, and let’s face it they’re being measured on code review coverage, so come hell or high water you’re going to do code reviews!
• And of course, regular professional developers know that code reviews, however painful, genuinely lead to better code, regardless of the pain involved in getting there.

What we have here, folks, is a social organization, complete with the crazy uncle, the embarrassing grandma and the pimply teenagers. And social organizations, as we’ve all come to know and love, are at their best when the forum in which they’re fostered exists for a reason that encourages the unstated, but nevertheless in-your-face activity of which those in the respective societal groups are desperately in need:

• Facebook? Getting a date. And then getting another one while simultaneously trying desperately to avoid the previous partner. Rinse/repeat. Seriously, I have no idea how kids manage today. At least when I was young and awkward we could hide behind the silence and foot shuffling of real face-to-face meetings. Now with a keyboard and the internet in the way, there’s nowhere to hide!!!! I’m off topic again… ahem…
• Linked-In? Getting a job.
• Myspace? Getting a clue.

You get the idea.

So code review as a social engagement… really? Parts 2 and 3 of this series of posts will examine how such interactions, fostered by social networking tools, are the best way to ensure code review gets done and returns value both to the participants and to the companies in which they work.

I have always loved “I’m gonna write me a new minivan”  from Scott Adams.  To me, it never gets old.  Originally published in 1998, the theme that applied then still does today: driving 100% of defects or bugs out of the code-base is a laudable goal, but is it really the right one?   I would have to argue no.  There’s no silver bullet out there that will find all software defects and solve issues automagically, and until there is, software development will continue to struggle with prioritization.  Unfortunately, we live in a world of finite resources and constantly evolving demands, but we can always dream about being Wally for a little while.

Jumping into the Agile fray: a technical writer's perspective

I’m a technical writer and technical writing in an Agile environment is somewhat like chasing those water drops.

You can run after those features, but early in the game there’s not really anything to hold onto.

So, how does one document a feature that will probably change from one iteration (or day) to another without chasing one’s tail?

Workflow can be your rock in that ever-changing environment. While the feature is likely far from finalized, someone’s gotta have an idea of how people are going to interact with it.

The developers can get you started, but the workflow people (at least in my experience) are the product managers.

So, while my agile dog chases water drops, this technical writer chases product managers—and if I still don’t have enough of a big picture outline for the feature or a collection of features, then the Chief Technical Officer is in my sights.

For major features “in flux”, the best way to get “good enough” content to meet your iterative deadlines is to channel the Australian shepherd within and herd the developer, product managers and testers into a room with a whiteboard and a marker.

In half an hour, you’ll get something workable. And maybe a chance to put your two-cents’ worth into the design.

What if there’s no workflow available?

If it’s a sunny day, go find a sprinkler to jump through. These days, that’s a chilly prospect indeed.

During the weeks that led up to Iteration 1, there was much work that went on as a team, and much that each team member did individually. As the Product Owner, my biggest task was to create a backlog. Sure, I knew what the main new features were going to be, but I still needed to capture this, and add other oft-requested features. I scoured every correspondence I had with customers, sales, support, development, and so on to gather this information.

After everything was said and done, I had a pretty massive backlog… a pretty massive, unprioritized backlog. At this point, I really didn’t know any good techniques for backlog prioritization (that would change after attending the CPO training with Mountain Goat Software). This training was not going to happen for a few months, but something needed to be done… so I did what any good Product Manager does…I used the ‘wet finger in the air’ technique. Now, my ‘estimations’ were based on a number of concrete data points and some not-so-concrete assumptions and anecdotal evidence, so they weren’t totally of the ‘wild-assed guess’ ilk. After a few more days I had my backlog read for the team.

While the backlog creation was going on, a number of team meetings were occurring. Two of the more important meetings involved creating rules for the team and preparing our definition of “Done” . I highly recommend spending some time up front on both of these activities.

Creating the team rules was a great exercise, because it was the first time the team sat down as a collective and decided what the rules would be. Many of the rules were not groundbreaking…things such as everyone’s opinion is equal, treat everyone with respect, don’t be late for meetings, and when and where daily Scrums were going to happen.

The best result from this meeting centered on the team’s communication methods. Everyone was already using email, so that was covered. Instant messaging was rolled out to the team, and everyone was to use it. Of course face-to-face discussions were encouraged the most, but there needed to be some way to let people know you didn’t want to be disturbed (unless something was urgent). Everyone created a Do Not Disturb sign, and when it was posted, it was to be respected. Sometimes people just need to focus on the task at hand, rather than constantly being disrupted. We came out of that meeting with a clear set of easy-to-understand team rules, and we posted these rules in our team conference room for all to see. Note… rules can and will change over time.

Next was coming up with our definition of Done. The team sat down for a couple of hours to determine what should/should not be included. Looking back, we thought we were cavaliers and were blazing new trails with the definition we came up with…in reality, we put together a definition that was pretty much in line with the ‘industry norm’. One thing that we did not include initially was code reviews…that is, for a story to be considered done, the code had to be reviewed by at least one other developer (who was not associated with that piece of code). During our Iteration 1 retrospective, we modified our definition of Done, and code reviews became part of it. In fact, this definition of Done may go through many, ahem, iterations before becoming finalized.

Finally, we needed to get our ‘room’ set up and have all the necessary supplies on hand. Our team decided to use a wall board with color-coded cards for the tasks. Green cards were for development tasks, red cards were bugs, blue cards were for testing tasks, and yellow cards were for documentation tasks. Now we just needed a board to pin these tasks to. We didn’t want to spend a small fortune on a big pin-board, so we got creative and used carpet under padding. (You can get a huge piece of this at any DIY store for next to nothing and it works like a charm.) We fastened it to the wall, put on some masking tape borders and labels, and we had ourselves a Scrum board.

So with our prioritized backlog, team rules, definition of Done, and Scrum room all set, we were now armed and dangerous, and ready for our first iteration planning meeting…TO BE CONTINUED.

The first meeting ever held with the whole team was intended to introduce Agile (Scrum) to them and get their buy in…we did not want to ram it down their throats and say we are doing this. At the time we were doing this, the concept of an Agile Coach was pretty much non-existent, so we were on our own. Our Scrum Master had been on some training, and thought for this meeting it would be good to try an exercise with the team to illustrate how Agile could work. So without any preamble or mention of Agile, everyone in the room was instructed to pick a partner, and then the goal of the exercise was explained. The goal was to navigate your team member around the room as many times as possible in 1 minute. Seemed pretty easy, until we told them about the twist…the team member that was walking around the room was to be blind folded. To add to the fun, our Scrum Master played the role of a roadblock, stepping in front of the blind folded people as they tried to circle the room, requiring new instructions to be shouted out to navigate around him. Once the clock started the chaos broke out, as 6 different people were simultaneously shouting out instructions trying to navigate their team member around the room, and around the roadblock. By the end of the 60 seconds we tallied total trips around the room, and came up with a number in the 30’s.

The 2^nd part of the exercise was quite a bit simpler, and merely had all team members walk around the room (no blind folds), and make their own decisions to navigate around the room and the ‘roadblock’. I’m sure you can imagine how much calmer the room was, and by the end of the 60 seconds we again tallied our results. This time we were well over 120.

So what was the purpose of this exercise, and how did it relate to Agile? Basically it illustrated the power of a self-managing team, and how the productivity of such a team can be magnitudes better when team members are given the ability to make decisions on their own, in real-time. After the exercise, we then introduced the idea of the team adopting Agile, what it is, how it could work, etc. In my opinion, doing this exercise first (and doing it without ever mentioning the term Agile) did more than a week’s worth of powerpoint sessions on why Agile is the way to go. The team was very receptive to the idea (at least most members, more on that in another blog), which set the stage for a series of follow on meetings to further flesh out what was really involved, and what needed to be done to prepare for our first Iteration. The next instalment in this series will delve into that preparation.