I believe it was in a conversation with Janice Fraser that I first started talking about DRY Documentation. It was certainly she (among others) who goaded me into actually writing this blog post. So I'm taking a moment on my WiFi-free (and generally amenity-free) United Airlines flight to SXSW to put pixel to screen.
DRYness is an age-old concept in the Agile space (to the extent that that's possible in a space that's only 10 years old itself) and it's elegant in its simplicity. DRY simply stands for Don't Repeat Yourself. The idea is that you should only do any one thing in code in only one place. If, for example, you are doing an interest rate calculation, don't copy and paste the code from one place where you need it to another: instead, move that responsibility to an object that reasonably should be responsible for such things, and do that interest rate calculation only in that one place. The reasons for this being important are manifold, but perhaps the canonical reason is so that it's easy to change: When the interest rate calculation changes, you don't have to go digging through your code to find all the places you do it, and make sure you change them all consistently. Instead, you change the code in only one place.
Hopefully this is old hat for most coders now, and hopefully you, gentle reader, will forgive me my oversimplifcations and conflations. The point is one of simplicity.
So now, let's shift focus to design documentation. The idea I'm trying to express when I talk about DRY documentation is one again of simplicity, though the drivers are perhaps a little different.
The mental model for truly DRY documentation is one in which every pixel on the page tells you something you didn't know before. Of course, like DRY code, it's worth being pragmatic. There are times when greater clarity can be gained by a certain amount of contextual restatement. But as a theoretical goal state, it's still quite useful to picture a body of documentation in which every last line tells you something you needed to know about what you're trying to build, and something you didn't know from looking at any other line in the documentation.
What would we notice about a set of documentation that adhered to these principles? Well, first, and most obviously, it would probably be a lot shorter than the documentation we're used to seeing. And that in itself is a benefit. Why? For a number of reasons. First, shorter documentation is in general easier to digest, and it's generally easier to find the relevant bit of documentation in a shorter corpus, all else being equal. (And of course, document structure and readability play just as big a role in a short document as they do in a longer one.)
Shorter documents are also easier to revise and maintain. And it's easier to find changes between versions, all else being equal. I talk sometimes about the 500 page PRD we got when we were developing one product, complete with two sets of revisions, also 500 pages each. Guess how easy it was for the developer to find the 2% of information that changed in each revision, and understand its implications to for the site? Guess how easy it was for the designer to be sure she'd changed everything consistently? In a DRY design doc, changes are more obvious, and more meaningful. Things jump out when they're inconsistent. And they tend to be more consistent, because the designs implied are applied more consistently across the product in question.
This brings me to another favorite topic: Principled design. DRY documentation is a lot easier to develop (and it's a lot easier to tell when your documentation is DRY) when your design is motivated by specific principles. For instance, when you decide, in the banking app you're designing, that all checking account features will use Cerulean Blue for their accent color, and all savings account features will use Prussian Blue, a lot of nice things happen. First, design questions become much easier to answer. The new Maximizer Account we've just added is a kind of savings account. Great! We know it's going to be Prussian Blue. (Or we can make a better informed decision that there should be a new point in the color family.) Second, it suddenly becomes a lot easier to document this fact. A one page style bible can capture this information, and when some new feature is implemented, it doesn't take any intervention from the VxD to make sure the new bits have the right color choices. Third, when some new feature comes along, developers roughing it out can come up with a reasonable early approximation of what it should look like, because they have principles to apply, instead of PSDs to pore over, looking for a non-existent visual treatment for the new thing they're just embarking on. This lets said VxD (and the IA) spend time tuning something that's close, rather than restating the design principles they've got in their heads, in the form of some new PSD file.
A fourth virtue is that suddenly all these color choices (or typography choices, or IxD choices,) have consistency, a consistency that our dear End User can actually pick up on. They don't end up feeling lost in a jumble of pretty colors, but start to associate the Prussian Blue with savings accounts, the Cerulean Blue with checking accounts, and, assuming the designer goes in this direction, that blue in general means cash accounts; green, stock and security accounts; reds and oranges, loans and credit accounts, or similar.
They may not be able to articulate why they know this, but they will perceive a solidity and purpose in the VxD, one that makes them feel safe and comfortable, and one that helps them use the application more effectively.
When coupled with a good domain model and a good information architecture, it suddenly gets a lot easier for the whole team to keep the design princples top of mind, and answer basic questions without having to consult a 500 page document, or even a 20-30 page set of wireframes and interaction designs. Hopefully they can answer most questions from a one or two page style bible, and by consulting the wireframe describing their grid system, and the one for the kind of module they're working on.
Again, the point is not to pursue this ideal to an absurdist end, but rather to continually ask oneself: Could this documentation be simpler? Did I cover this already? Could an existing design concept apply to the new area I'm covering? Restatement in the service of clarity is always to be lauded. Unfortunately, in practice, most restatement in the form of long design documents is just waste: Waste in that the documentation must be produced; that it must be maintained; that it must be read; that it must be understood; and waste in that it tends to obscure the princples of the design in favor of the surface of the design.
And of course, another agile principle comes into play: Refactoring. Often a second use of a given design treatment exposes new boundary cases and new pressures on the design, and the initial design needs to be modified slightly to accommodate both the new and the old use case. This is usually a simplfying force, and one not to be resisted. Let the documentation live, and reflect the deeper underlying principles of the design you're trying to express. Applied well, this rigor will help you to simplify and clarify your designs, and expose their essence.
When practiced well, DRY documentation will set you free, give you control and clarity, and communicate your design vision efficiently and clearly. It will also free your development team to do things more or less right the first time, and give them more time to work on the bits that need more love and attention.
An example of a one-page style bible, describing text treatments, spacing, backgrounds and grid structure in one digestible page.
This Friday at Pivotal Labs Boulder, we're hosting an evening of food, drink and discussion, to bring some of our learnings around Lean User Experience to the larger design community, and in particular to attendees of the annual international IxDA conference.
We, in this case, is a group of smart folks I've had the privilege to work with over the past year, a working group called the Balanced Team. This particular event is the result of the hard work of people at Cooper, Hot Studio, LUXr, SideReel and Atomic Object.
For the past year, we've been sharing ideas and discussing new ways to approach design and product development, to create better products, make happier customers, and reduce waste. We've been doing this while creating better integrated, more collaborative, more responsive teams. In that time, a number of us have been getting together on a regular basis to really sit down and discuss what works and what doesn't, and to try to distill these ideas into principles and techniques that are repeatable and practical.
We've been itching to engage with the larger design community to start to break down the culture of Big Upfront Design, the Cult of the Rockstar Designer, and the culture of necessary infallability; to fight the blind application of Waterfall and to disrupt the antipatterns we've found so antithetical to effective collaboration with agile development teams; to encourage patterns that allow designers to embrace early customer feedback, and to test hypotheses quickly; and most importantly, to foster a deeper collaboration with the very folks who have the biggest impact on what we build. We've seen over and over that, when done correctly, a light-weight process gives designers more control, not less.
It's out of this series of discussions that I first arrived at a framing of the problem space that I talk about in Enough Design, and it's also through these sessions that we've found a growing community of designers, product people, enterprises and other developers who are working to develop better techniques for integrated product development. We've found the conversation immensely valuable in our practice, and we hope to learn and share with more of you.
If you're a designer in Boulder for IxDA, or just someone who cares about usable techniques for bringing Lean principles into the development of compelling User Experience, come join us on Friday for deLUX. This is a free event, but space is limited, so please RSVP through http://pivotallabs.com/landing/deLUX.
Rob and I were recently asked by a client for some help justifying the choice of Ruby as an implementation language for their SaaS product. They were very happy with the results, but wanted to be prepared to answer investor and customer questions about why Rails was a good choice.
One way that I've been talking about Rails is in the context of what I'm calling "The ARC Model": Agile + Rails + Cloud. I'll borrow from my abstract from my talk at BizConf:
The Ruby on Rails Revolution has been one of productivity and efficiency, and has coincided with an equally powerful revolution in the ownership of technological infrastructure. The Rails approach combines agile methods with a highly productive language to allow developers to focus on developing business value, instead of developing plumbing. The Cloud Computing Revolution at the same time has changed the economics of infrastructure, allowing computation to become a commodity not worthy of developer attention, further enabling developers to focus on that which is truly valuable, Innovation. These three factors, Agile, Rails, and the Cloud, combine to revolutionize the economics of software development and information management, in ways that directly impact return on investment.
The question should not be, “is Rails a safe choice,” but “[how long] can we justify the expense of traditional development approaches.”
I think this kind of approach plays nicely to the strengths of SaaS.
In terms of large enterprise deployments, it's early yet: Enterprises tend to be conservative (about Rails as they are about SaaS) so most of the innovation has been in the startup space, with companies like Hulu being good examples of the disruptive power of Rails.
But that said, there have been some major mainstream Enterprise success stories. AT&T chose to dump a failing Java yellowpages effort in favor of Rails, with excellent results in terms of scalability, time to market, code quality, and performance. (There's a decent write-up on BuildingWebApps.)
We are starting to see major companies develop ever more mission/business/revenue-critical components in Rails. BestBuy built Remix, their new public API app, with us using Rails. We have one major multinational client who is rewriting their entire ERP system in Ruby internally. We have another major hardware vendor building new products using Rails.
Large companies tend to be a bit shy about talking about new technology initiatives, and we suspect that most Fortune 500 companies have someone doing Rails somewhere in the organization. There are a number of others we've spoken to who are using the technology to their advantage, but who aren't ready to talk about it publicly yet. But you can also search for job listings from major companies and see how many big companies are hiring Rails developers. We see them all the time.
Hard statistics are harder to come by, but Mark Driver at Gartner projected that there would be 4 million ruby programmers by 2013. We're already seeing the smart companies get huge efficiencies out of these new development models: efficiencies of cost, flexibility, and time to market.
We're very bullish on Agile, Rails and the Cloud. In the current economic climate, the reduction in risk alone is worth the cost of admission. Coupled with the qualitative benefits of being able to out-flank your competition, it's no surprise that we're continuing to see adoption grow so rapidly. The results are too compelling to ignore.
Jeff Sutherland, one of the creators of Scrum, has just posted a new blog entry in his Scrum Log: Pivotal Tracker: Now with a Burndown Chart!
I first met Jeff when we were both presenting on Agile process to a forum of OpenView Venture Partners portfolio companies, and have been a big fan of all he has to say about the adoption and effectiveness of agile practices in the wild.
Many thanks to Jeff for his help to make Tracker a better tool for scrum. We'll keep working with him to make sure Tracker is the best scrum tool it can be.
I just spent a wonderful weekend with 75 of the brightest folks I know in the Ruby community. My hat's off to Obie and the Hashrocket crew for putting together a really great, intimate conference in a beautiful location. It's refreshing to really have to struggle to choose which talk to attend from so many choices at each session. I know too many choices are a Bad Thing™, but the format made for great small sessions, and a wonderful thing happened: Everyone got to really meet and get to know everyone.
Among many others, I had the pleasure of meeting CJ Kihlbom, who nails a lot of why these conferences are so important in his post, The Business Value of Conferences.
It was really pleasant to present to a community of business leaders who understand the value of agile, and who are serious practitioners in their own practices.
A lot of you have asked for the slides from my talk, Agile, Rails and the Cloud, so I've posted them here.
Those of you who thought about coming but didn't really missed out. Come next year. You'll be glad you did.
On Wednesday night we hosted our first San Francisco Tracker Users Group (SF.TUG)
It was a great opportunity to meet more of our users, and hear directly from them about how they're using the product, and share with them some of the philosophy behind it.
We're excited by your enthusiasm and we will definitely make the TUG a regular event here in San Francisco, and we are planning to start one in our New York City offices soon. Please visit the Meetup group to join the discussion, and for more information and the schedule for future meetups.
Last week, Wolfram Arnold of RubyFocus interviewed Edward Hieatt, our VP of Engineering, and Davis Frank, one of our engineers, to try to get at the heart of how you build a scalable software development team.
The interview is posted on RailsLab, at http://railslab.newrelic.com/2009/03/18/scalable-teams-part-1-communication
It's a nice piece. We look forward to the second installment.
I'm very pleased to announce that Pivotal Tracker has won the coveted Jolt Award, in the Project Management category.
I want to thank the judges for selecting Pivotal Tracker above a category dominated by Agile project management tools, and for rewarding Tracker for innovation.
I want to thank the community who have used, evangelized, and supported Tracker, and in particular Obie Fernandez, Ward Cunningham, and Nivi; plus everyone over at Engine Yard for hosting the app.
And of course I want to thank and congratulate the development team and visionaries, particularly Dan Podsedly, Alex Chaffee, Rob Mee, Mark Michael, and Edward Hieatt for envisioning and then building the tool that we've come to depend on.
I'm pleased to announce that Pivotal Tracker has been selected as a finalist for the 2008 Jolt Awards. Thanks to everyone on the team for putting so much care into Tracker, and making it what it is today. Winners will be announced March 11, 2009 at SD West in Santa Clara.
Wish us luck!
For the last year or so, we've been inviting speakers to come visit us and talk about interesting things in the Ruby/Rails space, the agile space, and on topics related to software development in general. We see it as a great way to keep our developers on the cutting edge, and a number of speakers have used it as an opportunity to gather early feedback from our team. We've found the talks we've had to be very valuable to us, and are pleased to share them with the larger community.
To that end, we've posted a selection of our talks to our talks page, and also made them available via the Podcast section of the iTunes Store in both audio and video format.
We've also had a number of panel discussions in our Project Startup and are posting those talks as well.
We'll keep posting talks as we have them. If there are topics you'd like to see, or topics you'd like to present, please email us!