Best Practices for Lean Documentation: An Interview with Craeg Strong

Cameron: All right. Today we’re joined by Craeg Strong, who’ll be speaking at the Agile Development Conference & Better Software Conference East 2014, where he is giving a session titled Best Practices for Lean Documentation. Thank you so much for taking the time to speak with us today.

Craeg Strong: Thanks very much for the opportunity to speak today.

Cameron: All right. To start things off, can you tell us a little bit about yourself and your role at Savant Financial Technologies?

Craeg: Yes. Well my name is Craeg Strong and I’m a principal at Savant Financial Technologies, Incorporated. Savant is a software consulting company and of course I end up doing a bit of bid and proposal work in addition to working directly with clients.

Now, when I’m working with a client, I may work in a number of different roles including as an agile coach or a technical architect. I really started out a software developer and I still love to write code as I’ve probably done hardcore development over the years and a wide variety of programming languages.

Cameron: Do you have a favorite programming language?

Craeg: It changes. I try to learn a new programming language every year, so this year it was PowerShell. I was very pleasantly surprised that it was a lot more than I thought it would be. It’s a serious programming language, [and] great scripting language so I’m pretty happy with it.

Cameron: Fantastic.

Craeg: So [my favorite is] whichever programming language I’m using at the moment.

Cameron: Understandable. Now what led you to the idea of your session?

Craeg: I’ve been leading the adoption of agile practices on several projects since probably early 2000. Right after Extreme Programming Explained came out. For a number of different reasons, a lot of projects I’ve been involved with have been for a larger corporations or government agencies. There’s always a lot of regulatory compliance issues and a heavy weight governance structure or some sort of corporate software development lifecycle standard to contend with.

I’m talking about mission critical systems for insurance, financial services, and you know, criminal justice—working with the FBI for example. Documentation’s always been a significant part of that. That’s just how these organizations demonstrate their compliance. With agile practices they’re shining a light on business value and they’re making it much more obvious just how much time and energy is spent creating this documentation as opposed to delivering value or new software features. That’s what we’re supposed to be doing. There’s nothing wrong with spending time in an agile project to produce documentation as long as it’s valuable and necessary to support the overall mission.

Cameron: You talked about agile documentation there, how does the agile methodology of documentation differ from the traditional governance documentation?

Craeg: There are several important differences. First off, since agile methods really emphasize business value, ultimately a piece of software is going to provide that value rather than a piece of paper. On the other hand, most software of any complexity, mission-critical software of course is going to have some end-user documentation.

The emphasis on business value is important because it encourages us to look for more efficient ways to produce that value. In the case of documentation, is there a way that we can generate documentation? Maybe online help could be generated from the same source that produces the user guide for example? You might ask that question in a waterfall project but it’s more likely that you’ll discuss that on an agile project because they have this sharpened focus on business value.

The real big differences are visible when it comes to internal non-user-facing documentation. I’m talking about architecture, design, functional specification, that kind of stuff. In an agile project, we’re basically doing architecture, design, development, and testing all at the same time with rapid succession. The question is when do you even produce the documentation if you're constantly in that cycle? The documentation tends to focus more on the as-is rather than the to-be that you normally get in a waterfall project.

Cameron: What are the advantages to becoming more agile in the way you handle documentation?

Craeg: First and foremost, if you right-size the documentation, you can deliver more business value in the form of software functionality. That’s really what it’s all [about]; we’re here to develop and deliver valuable software. That means that we’re always laser-focused on the right things.

Second of all, an agile approach to documentation gives us more flexibility so we can more quickly adapt to change. We always talk about refactoring code. Well, how do you refactor a 200-page Microsoft Word document? That’s not so easy. If you had, for example, documentation that’s generated from source code or maybe some reports that get automatically generated, it would be great if by refactoring the design and refactoring the software, you’re simultaneously updating the documentation. There’s some really exciting things going on in the cucumber and behavior-driven development area about that sort of executable specifications. It’s very exciting stuff.

Cameron: You talked about the constant reflection and contact adaptation as being advantages to becoming more agile. Are there any disadvantages?

Craeg: Yeah, I guess the primary one I would point to is the resistance to change. Many agilists run into this. We’re often times coming in and challenging the status quo—trying to do things in a different way. It’s both human resistance to change but also changing established processes and established ways of doing business.

I’ll just give one quick example. In the federal government contracting space, some of the documentation might actually be written directly into the contract. If you want to make that documentation more agile, you might even have to make a legal modification to the contract. [Then there is] negotiation and lawyers—all kinds of stuff. It can actually be quite challenging to do that. The other thing is, even in a corporate space, getting approval for deviation from corporate standards could take a while. You have to watch out that that doesn’t cause project delays.

Cameron: You talked about those disadvantages and the one with the government and corporate makes a lot of sense. The fact that once you bring the lawyers into it, it has a chilling effect on that constant adaptation that you kind of [look for, and] it’s deterring. Do you think it deters people from even considering agile methodologies?

Craeg: I think you’re absolutely right. You hit the nail on the head. There are a lot of cases, both in corporate governance and also in federal government situations where it is better and the attitude is leave it alone. Let sleeping dogs lie. Don’t even open what could be a can of worms.

Cameron: Right, don’t shake things up.

Craeg: Exactly. It’s hard to put blame there because a lot of times they’re trying to solve a critical business need. They may think “The last thing I should be worrying about is am I going to be shut down because of some stupid compliance issue?” This is definitely a challenge.

Cameron: What should the expectations be for trying to implement the best practices for lean documentation?

Craeg: It would be great if you could just start Tabula rasa and jettison the corporate standards that might be waterfall-centric and just start and establish your own approach. In the real world that might be difficult—that might be frowned on. Rather than starting off on the wrong foot of noncompliance, what I’m trying to get at in my talk is really to present an incremental way forward. Saying let’s start with the world the way that it is and [follow the] Boy Scout rule of "how can we leave things a little bit better than the way we found them?" Just slight incremental improvements towards more and more agility, but always starting from a point of compliance. Don’t give people sticks to beat you with. If your project is doing well, it’s being run in an agile way, it’s producing value, and you’re meeting all the compliance, [as well as] all the governance structure, and mandatory items then that’s when you’re in a really strong position to negotiate and say, “Well, let’s make things more efficient for phase two or the next sprint for example.

Cameron: Is there a way to go about lean documentation or is it inherently a unique case-by-case practice that involves different strategies and customized approaches?

Craeg: In my session I do discuss several approaches that can be applied to pretty much any project. However, a specific combination of approaches that will work in a given situation is case-specific. Fundamentally it really depends on the business environment for the project. Is there significant regulatory compliance component? Where is the project sponsor in terms of the overall structure of the organization? How much clout do they have? What’s the criticality of the project? Is this something that the whole company or what Kanban calls an extinction level event? Where if we don’t do this we’ll go out of business or is this just more of a discretionary project.

These are forces pulling in each direction making things easier and making things harder. It’s important to understand those forces and then design the approach accordingly.

Cameron: There’s definitely a healthy balance between an art and science to it.

Craeg: Absolutely.

Cameron: A lot of times with documentation the next things that comes is reporting. How does reporting change with the switch from traditional to agile documentation?

Craeg: I think reporting is an area where agile does particularly well when you compare that to traditional approaches. The reason is that, especially if you look at Scrum, you’ve got regular iterations. You’re really making—in Kanban you have a continuous flow but you have average lead times and that kind of thing. You get in these regular cycles which natural lend themselves to reporting cycles.

We found that in a number of projects that our customers and stakeholders really appreciate the fact that at the end of every single sprint we can give them some reports about velocity and defect tracking and various things. It’s natural reporting boundaries that work very well in agile. It’s difficult to do that in waterfall. For the first couple of the phases you’re in requirements mode or design mode; there’s no code there. The metrics change all the time and then you have to rely on these proxy metrics like earned value. Earned value is just saying how well are we doing relative to what we originally scheduled? There’s no real guarantees there. I think with agile the reporting is surprisingly easy to do and effective.

Cameron: A lot of people look to best practices to achieve the utmost optimal function. Is it considered best practice to achieve optimal automation or are there cons that outweigh the pros with becoming optimally automated? That is to say is there somewhat of a law of diminishing returns when you become a certain amount automated?

Craeg: Yes, you have to look at it from a cost-benefit perspective just like anything else. Usually for me it’s when I start to do a task the third time that I say, “Well, I need to automate this now.” It also depends on the nature of the software that you’re working with. If this is a Greenfield project, a new project from scratch, or are you dealing with a lot of legacy code.

If you’re dealing with legacy code, legacy documentation, the types of automation approaches are going to be much more difficult to [set up]. The frameworks are going to be much more difficult to set up. There’s going to be a lot more upfront cost than if you just started from scratch and were able to use the latest and greatest tools, and you didn’t have any bad habits or a legacy code to contend with.

The cost-benefit curve is quite different for different projects. You really have to consider that. It’s really true that in some case you might look at certain tasks like producing a user guide or online help and decide that, “Yes, we could set up a content management system and have this complex process that would automate the production of these two documents, but it might be cheaper just to hire a couple of interns who are technical writers and do it manually. You really have to do that cost-benefit calculation.

Cameron: It seems like it’s almost you have to take into account not only the diminishing returns but the cost of learning versus the cost of unlearning the bad habits and unlearning the legacy systems you may have in place.

Craeg: That’s absolutely right. Certainly for example if you take the example of automated testing, some of the legacy code may not be set up to create automated tests easily. It can actually be extremely difficult. You don’t want to get into a case where implementing a new feature may take two days but implementing the test for that feature takes twelve days.

Cameron: Wow! Yeah.

Craeg: That’s the tail wagging the dog. The same thing with documentation; we don’t want to get into a situation where automating documentation takes longer than just doing it by hand. There’s a cost-benefit to take into account. Of course it’s not just the one time. If you have to produce documentation many times, maybe every sprint or every release, then that could justify additional costs up front, but you’ve always got to be aware of that.

Cameron: All right. Now switching gears here a little bit. You own a small consulting firm in both New York City and in Washington D.C. What led you to starting this company and why did you choose those two locations to base your operations?

Craeg: Yeah, we moved our headquarters to New York when we got involved in a large project for NYPD in the early 2000s. Then, initially our decision to expand to Washington D.C. was for business reasons. Federal government projects have a long sales cycle. They could take more than a year between the original RFP action and the final award, but they’re very stable and they’re long-term once they get going.

That’s pretty attractive to a small consulting company like Savant. Even better their budgeting process is locked in ahead of time, so once you’re on a project it really doesn’t matter what happens with the economy. In contrast, in New York City, all it takes is one Black Friday and boom! Suddenly you could have a consulting engagement terminated. They’re other reasons beyond the business reasons as well, because what I found time and again working with federal agencies is the work in the D.C. area really matters. We’re talking the FDA, TSA, screening, making travel safer and the FBI criminal justice systems. These are systems that people really depend on and they change people’s lives. It’s a really different feeling working in some of these programs.

Cameron: So, being based in those two areas has allowed you to make the most impact in multiple ways?

Craeg: Exactly.

Cameron: OK, Now, you’re also a self-proclaimed turnaround artists. This may be me reading too much into it, but in your opinion does the self designation imply that turning around a company’s practices is an art form? Or is there still a large by-the-book component to it?

Craeg: Yeah, at several points in my career I’ve been brought into a project that was in trouble to turn things around. The biggest example was a huge $100 million/year project for the NYPD. In order to turn around a project or a program the recipe always has the same basic ingredients, but the details are different. That’s where the art comes in. There are three places I look at: people, process, and technology. First you need the right people. Often in these very large projects usually means we need to get fewer and higher-skilled people. That can be a difficult conversation.

Second, sound engineering practices and that’s the agile practices, the Extreme Programming-type practices. The technology aspect usually involved reducing complexity. A lot of these large programs you have these huge complex architectures and that much complexity often can be reduced. It’s better to start with a small [and] a simple working system and grow and build on that, rather than trying to build a very complex system with many moving parts from scratch.

Cameron: It’s kind of one last final question wrap up here. We have the conference next week down in Orlando, is there anything you’d like to say to the delegates of Agile Development Conference & Better Software Conference East 2014 before they attend the conference. And of course even before they attend your presentation.

Craeg: Yes, I encourage them all to come and attend [my] presentation! Learn about lean documentation. I've definitely been to a number of these conferences this year and I’m really impressed. These conferences provide a great opportunity for networking and finding out what your peers are doing, the challenges that people are facing, and the good ideas that they have that might be helpful. I especially like going to the experience reports; learning about the actual steps that were taken in real life situations.

Cameron: That’s wraps up our interview for today. Once again this was Craeg Strong, principal at Savant Financial Technologies and he has given a presentation titled ‘Best Practices for Lean Documentation’. Make sure you check it out. Once again, thank so much Craeg.

Craeg: Thank you.

With twenty-five years of experience in information technology, Craeg Strong is the technical lead of the FBI CODIS project, shepherding its transition from waterfall to agile. Craeg started with Project Athena during his undergraduate studies at MIT and now owns a small consulting business based in New York City and Washington DC. An experienced turnaround artist, Craeg has successfully instituted agile practices in some of the largest and most complex commercial and government software projects. His areas of expertise are as a hands-on software architect and agile coach. Craeg is a Certified ScrumMaster, PMP, and contributor to the Apache Ant open source automated build tool.