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.

As Google Chrome climbs out of obscurity in the browser market and expands into a light-weight but fully functional OS, security seems to have become a top of mind issue over at chromium headquarters.

In the Chromium Blog, Chris Evans of Chrome Security announced a cash for bugs initiative, paying between 500 and 1337 USD depending on the severity for any previously undiscovered flaw.  I am glad to see Google encouraging the community at large to participate in hardening my current browser of choice.  As Chris points out, Mozilla was one of the first to embark on this type of program, but I am happy to see Chrome following suit.  Me and my online transactions appreciate it.

Hmm.  Maybe I should roll-up the sleeves and  invoke the  ”I’m gonna write me a minivan” approach and get the driveway cleared for the armored cash trucks.

But seriously, if you’re interested in helping out and getting a small reward for your efforts, visit the Chromium Security project.

Refactoring is a vital component for software developers, helping to prevent their projects from becoming unusable, and unmaintainable spaghetti code. Equally important to some developers, is the notion of refuctoring…check out this tongue in cheek look at Refactoring vs. Refuctoring. Be sure to check out the slide deck at the end.

Refuctoring describes the process of making your code unmaintainable by anybody but yourself.  I love some of the examples of Refuctoring such as “Pig Latin”, “Treasure Hunt” and my personal favorite “Stating the Bleeding Obvious”:

For example:

//initialize a to 1
int a=1;

Not that I’d ever do that (pause while I go clean up some code). Ahem, right anyways I thought I’d throw out some other refuctorings:

1.    “Catch me if you can” – Use so many goto statements that it will make anyone’s head spin.  Especially when you start adding backward goto’s.  Take a look at the CVS source code,  they have some nice (nasty) examples.

2.    “Giant tar pit of hell” – This is hard to blame one single developer as it really encompasses many developers getting together to create one big cohesive piece of crap.  You know you have a problem when you run out of printer toner trying to print these.

"Giant tar pit of hell"

3.    “WTF” – Using names that no one will know…ever.  If you create a bankaccount object, instead of calling it ‘x’, here’s a wild idea, why not call it ‘bankaccount’.  Let’s face it we are all guilty of this.

Now if you really want to be special (I don’t mean in a good way), try combining #1 and #3:

int afunction()
{

there:
   ...
   if(something)
   {
      goto here;
   }
   if(somethingelse)
   {
      goto there;
   }
here:
   ...
   if(somethingelseagain)
   {
   goto end;
   }
end:
...
return;
}

I have to admit, I’m not winning any awards either. It is certainly time to get on the refactoring bandwagon.

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.

How do you measure your software?  There are simple metrics that help with quality, such as keeping track of the number of bugs or security vulnerabilities in your system.  Trending these metrics is a no-brainer. When trending is in place, action can be taken because everyone knows 6 security vulnerabilities is worse than 5.  But what about other types of software metrics (and there are many)?  Have you ever heard of a maintainability metric? Halstead program volume? McCabe cyclomatic complexity?  Coupling/Cohesion?  The question becomes what do you do with these metrics and are they valuable?

Choosing a metric will really depend on what you’re after.  A good reason for measuring your code is to get predictable quality.   If you don’t have a metric in mind, the easiest place to start is with McCabe’s cyclomatic complexity metric.  I’ve seen many software organizations implement this as a good measure to help predict system “complexity”.  In other words, to help them understand where they may need to refactor or redesign their code.  McCabe cyclomatic complexity uses a measure of the linearly independent paths in the source code and is measured on functions or methods.

McCabe’s Cyclomatic complexity uses values to define what is complex.  Something greater than 20 is considered very complex.  You should think about re-writing that function because it is getting out of control.  Since the inception of McCabe’s Cyclomatic complexity metric,  several other variations have appeared, including Extended Cyclomatic Complexity and Plain Cyclomatic Complexity.  Back to the question, with so many metrics, which ones do you use and are they valuable?

No one can answer that question. In fact, software metrics is quite ambiguous.  It is hard to find anyone who says,’Thou shall use metric “x” because it will help you improve quality by “y” amount.’  The value “x” and “y” just don’t exist (although many have tried to put some data together).  Even more ambiguous are the values that may be defined with these metrics.  Don’t get caught up with these values; they are really arbitrary.  I’ve run into organizations where the majority of their code was deemed “very complex”.  Does this mean they should redesign their entire code base?  Certainly not. These numbers will vary depending on what you’re building.  So be careful if you use the “recommended” values for any metric.

Instead of focusing on the value of your next metric, what you really should be doing is trending that metric.  Find out if that value went up or down.  Up bad; down good.   Taking it one step further (if you really have a “thing” for the values), you could start by finding the standard deviation of your metrics.  In other words, find the average value of any metric, say complexity, plus the standard deviation.  Now, you can keep track of that value knowing that if you go outside your bounds of deviation, then you may want to look.

Software metrics certainly have their place and can help give some predictability on your system.  In another post, I’ll talk about how you can take some low level metrics for the developers and give them insight into the software system.

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.

In my previous blog post, we talked about the value of compiler warnings and reasons to have source code analysis. Now, I’d like to get into the value of coding standards and touch on how you can fit this altogether.

Coding standards are a set of rules or guidelines usually created as part of an industry. The goal is simple, provide guidelines, so you can create better code and increase your code quality. Probably the most common coding standard I run into is called MISRA C. This is a standard created for C code in 1998 and revised in 2004. A new standard from MISRA was released in 2008 for C++ code. MISRA was developed for the Motor Industry but has since been adopted by many other industries. Other coding standards such as Joint Strike Fighter are focused on other industries, such as the aerospace world.  And there are more generic types of guidelines, such as the Power of 10, which contains more high level practices.

Either way, these standards cover everything from simply “thou shall comment code” to more specific coding no-no’s. So, how do you apply these to your process?

The advantage of these coding standards is that compliance is something you can quickly scan for using source code analysis. Any source code analysis tool worth its salt incorporates these standards into their issue checkers.

Implementing a solution for developers is key to this process. After developers check to ensure there are no compiler errors (or warnings!) they can run another process (or integrate into your existing process) using source code analysis techniques to find infractions with various coding standards in the code.

Remember that compiler warnings can be very helpful, so use them. Don’t be surprised when your source code analysis vendor asks if you are using your compiler warnings on your next checker feature request. Once you have cleaned up your compiler warnings and you want to take the next step to improve code quality, there are many good coding standards that will bring up the quality of your code. Use source code analysis tools to help you automate this process and you will guarantee a better report card.