Want to get rolling with a Source Code Analysis (SCA) tool as efficiently as possible?

“Do what the smart companies do,” says Mark Grice, a Klocwork Director and Manager of the International Reseller/Partner Network.

In our last discussion, Grice outlined three best practices for SCA tools selection: involve your developers, limit your selection to market-leading tools, and identify a deadline.

According to Grice, smart companies take those best practices and:

“After the six-month period,” says Grice, “a company will widen its deployment circle and get more licenses.”

On the other hand, Grice says it’s also possible that the company will decide to try another tool from their panel of tools. They won’t need to re-evaluate because they’ve got a short list to pull from.

“They don’t lose, whichever way it goes,” he says. “During that six-month period, they got value from that tool by applying it to their codebase, learning about SCA and cleaning up their code.”

Mark Grice in a more peaceful moment.

The last time I spoke to the Klocwork Director and Manager of the International Reseller/Partner Network, he outlined 7 habits of highly ineffective Source Code Analysis (SCA) tool selection.

Among those terrible habits, he described an SCA tool-selection process that involved endless feature comparisons and massive checklists of irrelevant requirements.

His head almost exploded, but on this day our SCA guru was calmer.  Clearly, he’s been using relaxation techniques or drinking some of the good stuff, like acai juice.

According to Grice, successful SCA tool adoption involves three key steps:

1. Involve your developers in the process.
   “Developers understand what their requirements are,” Grice says. “And that means your selection criteria will be more realistic and achievable, and it will focus on what’s relevant to the organization’s software and environment. Developers are also best equipped to assess the SCA results.”
2. Limit your selection to market-leading tools with the functionality relevant to your software needs.
   “For example, if MISRA compliance is something you care about, then make that part of your selection criteria,” he says.
3. Have a game plan with a path and a defined end. Work toward a goal that’s realistic—spend enough time, but not forever, finding the tool (or tools) you need.
   “Have a good idea of what will constitute success, and be prepared to make a decision and move on,” Grice says. “Avoid paralysis analysis—unless your goal is to just waste time and money and contribute nothing to improving your software.”

That’s it for today. Grice is off to yoga class (um, or a pub). Stayed tuned for the next post in this series–How smart companies adopt SCA tools.

Mark Grice is a pretty unflappable guy, but when you ask him a question about barriers to successful adoption of Source Code Analysis (SCA) technology, he starts to splutter.

By the time users hit the help documentation, they’re already snarly. Yeah, some people read the documentation first before using the tool, but…

A lot of people just want to dive in and start using the tool. And when I’m stuck I want answers. Now, already!  You might think it’s stupid-user error and I might think it’s stupid software design, but who cares? I want help right NOW.

Troubleshooting information lives or dies by the search-and-I-better-frickin-find-what-I’m-looking-for mentality. How do we look for this help? We copy and paste error messages into a browser and search.

When my ideas about organizing  troubleshooting information compete with how Google finds stuff, Search Engine Optimization (SEO) carries the day.  Or at least it should. Of course, there are SEO factors that put help documentation at a disadvantage, but that’s another topic for another day and I’ll let Tom Johnson do the talking on that one.

What does this mean for me, a technical writer?

Well, if two (or 5) of our tools throw the same error message, I’m going to have one page for each error message and have instructions on that page that explain how to fix it in each tool. Yeah, it’s nice to have tool-specific help information, but Google gives more weight to page titles and URLs. For good measure, I’m going to repeat the error message in the body of the page and format it in bold or italics.

Sarah Maddox highlights elements of what makes a good error message (including some hilarious examples of bad ones), so no need for repetition.

Aside from clarity, what do I want in an error message?

Firstly, I’d like to be able to copy and paste it.

Secondly, I’d like the solution to be stated.

As an added bonus, I’d like to be provided with a link in that message that would bring me to the dialog where I can take remedial action. Then, I won’t even have to look for help information. I can just fix it. Here’s an example of one these helpful messages from our Eclipse plug-in:

See? Documentation not required. The solution is outlined, and you can click the link to get to the license dialog, where you can check your host and port information.

Hmmm. Maybe that would put me out of a job. Sergey, please change that message to:

ERROR:FROZEN:BAD LICENSE.

I have a mortgage to pay here.

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.

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 remember that idyllic summer day when I saw my very agile dog Maggie jumping through the sprinkler. I laughed until I cried. And then I thought:  This reminds me of what I do for a living.

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.

Going beyond "getting started"

“Now what?” is that uncharted territory between “Getting Started” product guides and the challenge of incorporating a new tool into day-to-day activities.

In fact, I’m convinced that “Now what?” is one of many creatures inferred by the “Here be monsters” legend inscribed on uncharted regions of old nautical maps.

I think of it like this: You buy an exciting adventure package to Costa Rica. You put your money down. The tour operator hands you a map. And then you end up…in Holland.

Time to call your emergency number:

You: “Can you help me out? I was supposed to go to Costa Rica and I followed the directions, but I’m in Holland.

Customer support: “Let’s go over what happened and take a look at the directions.”

Customer support reviews your actions and examines the map. (They are incredibly patient, discerning and resilient people, these customer support types.)

Customer support: “It appears that you took a wrong turn at Albuquerque (except it’s pronounced Albekoiky).”

Then you’re put on the right road. A problem report gets logged against the map-makers to clear up whatever ambiguity there was. Now you and future travelers can end up at the intended destination.

Excellent.

“Okay. I’m in Costa Rica. Now what?”

Exactly.

This is an issue sales engineers frequently encounter in the field. It is also something that Geoff Babb touched on in his response to Helen’s post, “Exposing our soft underbellies“,  about moving documentation to a wiki.

Useful examples are great, but finding the right scenario can be difficult, particularly when customers can range from a couple of guys in their basements to companies with thousands of developers.

With a large documentation set, it’s difficult to keep up with new features and include scenarios that are relevant to everyone—a major rewriting effort indeed.

During a meeting where we presented our documentation plan for moving to a wiki, “Now what?” showed up again.

I don’t remember putting “Now what?” on the list of invitees. But it appears that there’s no stopping that beast.

Our move to a wiki means rewriting a helluva lot of material anyway. Might as well take on the beast.