At the risk of sounding like a co-dependent, in this post I discuss coping mechanisms that a “big picture” technical  writer (say, like my friend Beulah) can use to adjust to working in the granular conditions of an agile environment.

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.

Just came across this post about the 5 code metrics you need to watch.  I thought it was worth mentioning as I just blogged about this below (including something similar a while back).  These are interesting metrics and more high level, but certainly important.  I like labeling duplicated code as something important.  I think we often forget how much we reuse code and have the same mistakes in many places.

So awhile back, I was begging for some good statistics on Agile adoption, since at that time, there really wasn’t anything substantial to sink your teeth into. Well, a new report from Forrester came across my desk, and it helped to strengthen what most people believe…that Agile processes have overtaken Waterfall as the development methodology of choice. In this report, which cites information gathered from a Q3 2009 survey of IT professionals, it states that 35% of respondents said that Agile most closely reflected their development process, while waterfall processes came in at 13%. I would even argue that iterative development could possibly be included in the Agile bucket, not because it is full-fledged Agile, but it is a baby-step in Agile’s direction. Perhaps I’m stretching things there…

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….

The last entry in my Going Agile series will look at the retrospective meeting.

The retrospective meeting is held at the end of every sprint/iteration, and it is the time to discuss what went well, and what could be improved in the next sprints. Some people will say the Product Owner should be in attendance, and some believe the PO should not. IMHO, the PO is a part of the team, and should be there…and in our case, I was. We weren’t sure how to solicit input from the team, so we decided that everyone should take a few minutes to write down their thoughts, and then the Scrum Master would read them out. This was a good way to eliminate the classic, “I was just going to say the same thing as Bob” response. After all the responses were collected, we realized we had 3 main things to address:

1)      Testing and documentation struggled…they were too heavily back-loaded

2)      Code reviews were determined to be essential but weren’t being factored into estimates, etc.

3)      Our team velocity was nowhere near what we thought it would be

From these things we made a few adjustments for our next sprint (again, these decisions were made by the team as a whole). Our developers stopped working on new stories 2 days before the end of the sprint, and would then focus on testing and documentation. This would help alleviate the avalanche of new functionality that would hit the testing and documentation team on Friday afternoons. Code reviews were added to the definition of ‘Done’ and were factored into to estimates.  For the 3^rd issue,  we found one of the key issues to be that developers just weren’t given dedicated time to code, and as such, could be interrupted at any time for an impromptu meeting, or discussion, etc. We decided to implement a Do Not Disturb mode for the developers, and if they had that DND sign up in their cubicle, or on IM, then they were not to be disturbed.

The retrospective is a crucial part of the continuous improvement process, and time must be dedicated to it. The first few are extremely important since that is when the warts are most obvious, but minor tweeking  may never stop.

I’ve enjoyed sharing my experiences about my first Scrum team, and I hope it may provide some ideas for your team. If you have any Agile/Scrum experiences you would like to share, I’d love to hear about them. Chances are others will stumble across the same problems at some point as well.

Part II – Joy is the word…

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.

I just couldn’t resist using the classic spaghetti Western as the title for this instalment of my Going Agile series because it a) it was an awesome movie, and b) it truly sums up that 1^st iteration of ours. My last post was all about the 1^st iteration planning meeting, and how it was such an exciting and productive time for our team. We came out of that meeting a little weary, but extremely motivated to get to work. We were also just a tad naive.

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.

Now that the New Year is upon us, I thought it would be a good time to add another chapter to my Going Agile series. My last entry left off at the point where we had prepared our backlog, created team rules and defined “Done”. Now we were ready for our first Iteration Planning 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.

Our new documentation wiki is up and running!

For awhile it seemed like we’d never do it. We have a team white board that records our panic level, and for several weeks, the level was up around “hysterical” and “wanting to open my own daycare”.

We also have a white board in front of the doc area, in a hallway where everyone walks by to get to the kitchen.  At one point when we were particularly frustrated with MediaWiki, the topic was “names for the new doc wiki”. A few good suggestions:

the gaping maw, or "the wiki is never done"

And the best one, though we decided it would be unprofessional to make it official:

RTFW

Fortunately, when I was ready to throw in the towel, our IT guy stepped into the ring and beat MediaWiki into submission. He installed extension after extension, found a search engine that worked for us, and configured a great PDF creator. He moved the entire Wiki a few times to improve performance and security. And he was much more tolerant of the state of MediaWiki’s documentation than I was.

So, if you’re a small documentation team thinking of moving to a Wiki, what do you need to make it work?

• Someone outside the doc team needs to handle the technical side, so you still have time to do what you do best: write user documentation. In our case, besides IT, one of our senior developers ended up learning more than he probably wanted to about MediaWiki. He made the wiki the source for context-sensitive help for detected issues; each of these wiki pages allows you to switch from English to Japanese. Some of our users have no access to the internet, so he also wrote a script that exports the wiki to static html for packaging with Klocwork software.
• Read blog entries like Tom Johnson’s Ramping Up on MediaWiki to remind you that you’re doing the right thing.
• When the voices in your head whisper that it’s impossible to both switch your help delivery mechanism and reorganize/rewrite the entire help system in just a few months, take a pill or something.
• When your inner perfectionist rears its ugly head, repeat this mantra: The wiki is never done. The wiki is never done.

In the end, despite feeling like we were being drawn kicking and screaming into the gaping maw of hell, we love our wiki, and we hope our users will too. And users, if you don’t like it, you can change it!