Showing posts with label software archaeology. Show all posts
Showing posts with label software archaeology. Show all posts

Monday, January 6, 2014

Developing in Fits and Starts

In biology, the punctuated equilibrium theory suggests that evolution happens rapidly, followed by long periods of stagnation.  Organisms change and speciate, and come to an equilibrium for a very long time.

Today, coding made me think that development is a punctuated equilibrium, too.

I was working in a fairly large codebase with some deep dark corners.  Nothing far off what we all do; nothing special at all.  I was having trouble getting all the details into my meatspace, but was managing to get things done, code was progressing.

And then I hit a wall of "what the what?"

Happens to me from time to time, when a little detail will stymie me for five minutes, ten minutes, a half hour. Where you twist your head sideways to look at the code and wonder what the heck the code is doing.

I ran into a few of these today.  I figured them all out, but they each shut me down for longer than I would want to admit to anyone:

  • Where the heck is that css parameter getting set?  I can see it in the browser's "inspect element", but I can't see where it's coming from in the code.  Not in the HTML, certainly, and not in the CSS.  Oh, there it is, right there in the TypeScript file!
  • Why the heck is this object serializing to JSON differently than to string?  Does the ServiceStack.Text call the ToString() method under the scenes when serializing objects?  Is the "override ToString" code section here followed by ToJson() example a typo, or is that how it is supposed to work (My legacy object has a ToString() and a ToJson() method on it, and the service stack uses the latter.  Makes sense.
  • Where is the bug in my KnockoutJs code?  I'm sure I've forgotten a set of parenthesis somewhere, but I can't for the life of me find it.  Oh there's the little bugger.  Oh yeah, when I want to do a visible check against an observable property, I can check it directly, but when negating, I have to invoke it as a function.  A known property of the library, but darnit if I don't forget that sometimes.

Coding along happily, then boom, stuck in the mud.  Trudge, trudge, trudge, finally get out and get back in the rhythm, then bam, back in the mud.

Is my solution evolving?  Is that why developing happens in fits and starts?

Wednesday, November 27, 2013

The Myth of the Transition Plan

When an employee leaves an organization, there is a weird period where the organization panics a bit. Maybe it was clear that the outgoing employee was awesome at creating things, but maybe a little weak about documenting them.  Or maybe the employee was a single point of failure on a couple different systems or components, or just legacy knowledge that will be orphaned or disappear on departure.  Could even be that the outgoing employee was the only trained backup for a couple people who have already left.

So what do the organization do?  It creates what's called a "transition plan."  This plan is supposed to reduce the outgoing employee to a set of disciplines that need to be transitioned to as many people as the responsibilities dictate.  What's the typical response to this? 


This transition is supposed to take place through a number of mechanisms: in person meetings, tutorials, documentation.  When an individual announces their departure, it's often kept quiet a couple days as possible negotiations, or risk mitigation, or simple grieving happens.  If the employee was kind enough to give two weeks, and the organization isn't one that kicks people out more quickly, there's usually a maximum of eight days to get a transition done.  As a result, a transition is often ill-planned, hastily thrown together, and often misses some key things that get forgotten in the rush.  

I've been thinking about this a lot lately.  In my time in my current employ, I've inherited a lot of legacy information, either suddenly from another outgoing peer, or by being the only one to dig through the detritus left behind when everyone who knew anything about the system was long gone and unavailable for question. In fact, I've dug through so much legacy code to discover crusty old systems that I adopted the "Software Archaeologist" moniker.  Note, I find the digging through code fun, but can be construed as a symptom of poor knowledge transition and organizational knowledge retention.

Why Transitions Are Rather Pointless

Transitions are lossy.  When a few people get into a room to do a transitional walkthrough, say of some code, what people don't realize is that there's not much hope of retention of the entirety of the information. The presenter boils everything down to only what's absolutely critical, and then the audience takes away only a fraction of that.  Spaced repetition would help this somewhat, but this information will likely be broadcast at most once.

The outgoing employee has no motivation to excel.  Sure, people are going to be professional, and no one wants to leave ex-colleagues in the doo-doo.  Can't burn those bridges!  But I've never seen anyone put anything remotely approaching enthusiasm into a transition plan. They do as they're asked, but if they don't do a great job, what's the worst that could happen to them? There's not a single motivating factor to make sure what's left behind is a well-oiled machine.  If an outgoing employee is leaving now, it's very likely you've not had their enthusiasm for a long time anyway.

Recipients are not engaged or open to transition.  The people receiving the knowledge transfer aren't leaving.  They didn't pick the timing.  They were not looking for more work.  Because they already have a job that doesn't involve what's being transitioned to them, they're likely already busy with what they're doing and aren't thinking of this new task or set of responsibilities. Maybe they don't want this new work or type of work, see it as an imposition, or see it as the company trying to put more pounds of sticky mess into an already overflowing bag.  A transition may be very demotivating to the remaining worker, and I've never seen someone say to those recipients, "Hey, I know you're already overloaded, but we really appreciate you stepping up and picking up this extra workload.  Here's how we plan to mitigate this departure's effects on you."  Never.

For infrequently used knowledge, the transition survival rate is basically zero.  When an employee transitions out, the proactive part of what they were working on often gets put on hold, and those transitioned to are basically there just to maintain the status quo of those things, meaning that the transition recipient may not use the knowledge for weeks, months, or even years.  By then, even the 10% of the material they understood from the transition has decayed significantly.

Transitional knowledge doesn't survive a second transition.  Given that the transition is lossy, and that information that is broadcast is often not fully received, you can call this observation "simple probability theory."  If information has a 10% chance of surviving a transition, then the second transition has a 1% chance of transmitting the information.  Even if you think the transition rate is higher, subsequent transition success diminishes with time and number of people.

Managers are not accountable for the information, only "planning the transition."  When a manager's employee leaves, they have to scramble.  They often do not have enough bandwidth to absorb the loss of the productivity of a full team member, but they have to do the best they can.  They can write up a transition plan, schedule the meetings, and walk away saying, "well, I did all I can do."  That's true.  Once you let your organization get to that point, that's the best you can do.  But when the transition doesn't survive for the long term, and there's inefficiency due to current employees having to mine out information from source or worse, there's no managerial accountability for the resulting drag on productivity. 

What Would Work Better

Okay, so I can't give some prescriptive advice here based on what's worked better for me.  I've never seen good transition.  Here's some quick hits that would improve the situation, though.

Don't need transition.  Just don't need it.  It's that simple.  Transition, as I've described it here, is not absolutely required.  These transitions often occur in an organization that is ill-staffed, and everyone has a unique, non-overlapping set of job responsibilities.  If no one else works on the same thing as the outgoing employee, then the amount that has to be transitioned is 100%.  If there is sufficient overlap, backups, and bench strength, transition is often not an issue.  Managers should regularly analyze their teams for single points of failure and work diligently to ensure knowledge is spread around.

Have an employee DR plan. It's amazing how many organizations plan for system outages and put DR plans into place for when computers go belly up, but absolutely fail to recognize that they are guaranteed to have permanent personnel outages eventually, and that they can't necessarily predict when those will happen. Most organizations plan for months to do a single day of system testing to demonstrate that they can handle a building or a system outage.  Every application we write has to have a fail-over story, a way to recover if the database is missing or an app pool spins out of control in IIS, chewing up all the resources on the app tier.  The same organizations that spend millions on that do no visible planning for permanent employee outages, which happen all the time.

Transition to documentation. If you do find yourself in a position to need to transition information, it is not sufficient to have a meeting to do a simple code walk-through of the most common path.  The most common path should be documented in an architectural doc already.  Have a walk-through detailing the exceptional cases, how to troubleshoot common issues.  And in that session, take notes.  Then publish them to your internal knowledge base.  You do have an internal knowledge base, right?  Oh, dear...

Maintain an organizational knowledge base.  If you don't have one, start one.  As a leaf-node resource, you may not have much say in where this is, but if you're a manager, get this up as a shared network drive at minimum.  Better still, some kind of document management system.  SharePoint document libraries are an obvious answer in Microsoft shops, and I've used a SharePoint wiki as a knowledge base for a few years now. It's searchable, editable, auditable, and shareable.  But whatever you do, have somewhere that this information can sit and be discovered later.

Transition to Video. I've actually used this strategy on my own departure previously.  You'd have to ask the recipients whether it worked effectively though.  When the time comes, interview the outgoing employee. Ask for the knowledge to be presented, and video record the whole thing.  Often, this is faster than writing all the documentation down, is less onerous than sitting and writing documentation (so you have a better chance of getting better information), and if only 10% of the information is retained, you can go back and mine the video for more.  And you can possibly produce documentation from the presentation if need be.

Encourage a culture of sharing.  This falls into the category of not needing to transition, but retains a different flavor somewhat.  If your employees self-organize, if they pair up on coding and other job responsibilities, if they regularly collaborate, then you have a much diminished need for panic transitions. More people will share ownership in more artifacts.  And the flatter the hierarchy, the more the management shares that ownership, and panics less.  

Maintain a culture of transition.  These transitions are often a surprise because an outgoing employee does everything possible to hide the potential that they might be leaving until the last moment.  This can be because the employee is hedging and thinking about not leaving, the deal can fall through, or a number of other scenarios.  There is fear that once identified as someone who might leave, opportunities will cease coming your way.  Thing is, everyone is a candidate for leaving at any time, if they are an individual of talent that is visible in any way to the outside world.  And if they're not, they're probably not good enough for you to want to keep (because they're not competitive on the market, say).

Conclusion

Losing employees is expensive.  Locating, hiring, and retraining a replacement employee can cost half an FTE or more.  You lose more than the employee's productivity.  You lose their organizational memory and their contribution to both present and future corporate culture.  Given the amount of time spent transitioning and the retention that results, you're better off not bothering with so-called "transition plans" and letting your employees, both staying and outgoing, be productive through the transition. 

Transition is inevitable, though, so you have to have a plan for talent management that involves identifying performers, keeping them happy, making sure you know what they want, and how to help them move on when it's time. This isn't an easy thing to balance, I'm sure, but it would mitigate the risk of loss of organizational knowledge and disruptive schedules if an organization could do that correctly. And knowing that you can't keep everyone (and you may even want some of them to go), develop and nurture a culture that supports flexibility and sharing. 

Thursday, May 10, 2012

Software Archaeology


What is a Software Archaeologist?

Most of us that work in corporate Information Technology shops are Software Archaeologists. Every organization I’ve seen and many I’ve talked to has a built-up layer of legacy applications that are old and in disrepair. While many of these applications are used daily, it may have been years since they were opened, rebuilt, refactored. The source code may be missing, and the original authors may be long gone from the organization, taking their knowledge of the application with them.

It’s this organizational brain-drain that turns many of us in corporate IT into Software Archaeologists. Every time a developer has to don his leather fedora and dive into an ancient codebase with little to guide him but a few cryptic comments littered in the code tomb, and a document that some long-ago intern put together in a half hour to meet a letter-of-the-law requirement in the then-current SDLC, that developer becomes an archaeologist.

Being an archaeologist means digging through all the various eras of coding.  Being able to parse the Scatter-Gather patterns in Visual FoxPro, say, or to unwind the data calls from the business objects that were once part of the popular CSLA methodology - those become part of your everyday toolkit.  What about that legacy web services architecture that passes around typed data sets everywhere?  What about that .NET 1.1 Remoting service layer you built?  You need to know it all, and to hop back and forth through the disparate layers, gathering golden icons and dodging rolling boulders all the way.

Even those developers who only develop new applications need to be versed in Software Archaeology, because nowadays many internally developed applications are on end-of-life platforms or hardware, being scoped for moving to the cloud, or are being revisited as part of Business Process Reengineering.  These developers need to get back into recently rewritten code and re-envision.  You have to know how to dig.

As a Software Archaeologist it pays to know not only today’s architecture, but those of the past, especially those that were popular in the organization around the time the code was written. But not limited to the standard architectures of the day. Organizations hire people who come in to try their hand at something new, or bring in some flavor-of-the-day architecture, tool, library. As a result, one-off applications are going to be unearthed. As architectures become archeological layers in the binary geological strata of an organization, so do architects become archaeologists.

I have a deep appreciation for all my colleagues who perform software archaeology on a daily basis.  Those whose jobs are just to maintain those applications that time has forgotten.

I respect the dig.