Back when 37signals was consulting, we gradually weaned ourselves off of documentation. It’s normal practice in the design world to produce lots of artifacts. You see IA diagrams, flow charts, OmniGraffles, and all kinds of illustrations of what the final product will be. In the early 2000s we noticed that our clients only cared about the deliverable, so we dropped nearly all of the paperwork.
Since then we’ve often advised other companies to spend less time on paperwork artifacts and more time on real prototypes. But just saying that isn’t enough. How does a team that is accustomed to a heavy paper flow wean themselves off of it?
I used to think design teams made so many diagrams and documents because… well, they like that sort of thing. Now I’m suspecting there’s more to it.
A symptom of a bottleneck
I’m suspecting documentation is a symptom of something else: a bottleneck in the value chain. Think about it. Design ideas are perishable. They have to be acted on right after they appear, or they fade away. So what happens when your development process can’t absorb design ideas at the rate you produce them?
It looks like a dilemma. You either:
- Produce design ideas at the pace of development (which is far slower, by definition of the bottleneck) or
- Freeze ideas in the form of documents, diagrams and requirements until they are ready to be thawed and consumed later.
I suspect #2 is what happens in a lot of firms. The throughput from design to implementation in those places is so low that pacing design with development doesn’t seem feasible.
At 37signals we’re firmly in the #1 camp. Designs go from concept to HTML (often in-app) without any deliverables in-between, and then from HTML mock to fully implemented feature in Ruby or JavaScript again without intermediate artifacts.
Healthy pressures on design, programming and scope
Pacing design with development puts a few pressures on the company that we think are healthy.
First it means all the designers should be proficient enough with code to implement their ideas, at least statically.
Second, the programmers should have enough skill and leverage from their tools (an important factor) to produce meaningful work in short periods.
The third point concerns how we manage and define scope. In order for design, implementation, and review to all happen while the plate is still hot, each piece has to be small. If we bite off too much work at once, then design will go on too long before development can join in. When there’s too much to build at once, review becomes unfocused because the set of variables to evaluate is too large. So whether the project is small or large, we factor the scope into smaller component scopes, build them one at a time based on their dependencies to each other, and evaluate the results step by step using the app ourselves.
The ideal loop
The ideal loop is short enough that you can still feel the spark of your idea and you’re still curious to find out if the decision was right or not as you click through the implementation. You can’t fully judge a design until you’ve tried it in action. The clothes simply look different when they’re on. If there are too many changes to evaluate at once, we can’t tell which of the changes contribute to the improvement or regression and how those changes suggest future steps. Moving in one direction in one feedback cycle is easy. Moving in ten directions in the same cycle is too hard.
I hope this look at our process gives you a clearer picture than a bare statement like “documentation is bad.” Documentation may be necessary when your throughput is low, and that’s an opportunity to see documents not as charming deliverables but as warning signs of a deeper problem in your process.
Erik
on 06 Jan 12As a management consultant I can both applaud the “documentation bad” philosophy as well as confirm that there are times when the paper trail is necessary.
I have been on system design projects where the reason for the paper was CYA. It CREATED a bottleneck on purpose, to give those on the client side time to review what is being made (which they didn’t like to do) OR pursue the strategy of gaming someone ELSE in the organization to give the sign off OR use the pressures of development to get the team to move forward WITHOUT sign-off. All nice ways to cover your tracks as middle management. That’s the bad kind.
The good kind is when a project is unique, development is more complex, and the requirements aren’t clearly understood. The paper trail in these cases is what brings the client down to the table to say “yes, this is what we need” or “no, it’s missing X.” It also gives the developer something concrete to review with the client to make sure they really understand what they are building. The reason it needs to be done in paper is because when the business process is complex generally the developers don’t have the skill set to winnow out the real requirements and facilitate the conversation. That a specialized skill set (mine), and I can’t code. So it’s paper, but PRODUCTIVE paper.
In cases where the product is your own and your team has been working in the same business processes for years, where it’s a matter of evolution and innovation rather than invention, then I agree, cut out the middle man and his paper.
But when that can’t be done, hire me ;)
Fernando
on 06 Jan 12Great post. I’m afraid the company I work for, a multinational company, seems to be in #2. And like you said, this is a sign of a deeper process problem. I wish managers could read. :-(
seth godin
on 06 Jan 12I think we have to acknowledge that it’s a happy accident that your throughput matches (almost exactly) the complexity of the work you create and the demands of the marketplace.
In and out are evenly aligned.
But it’s an accident.
Consider architects, for example. Clearly a building can never be built as fast as it can be designed. As a result, the organic method for putting up a skyscraper is design many times, build once. Same with designing a garden. Or publishing a book.
Or consider improv comedy. In this case, the throughput is actually higher than the ability to design it, so you just go with that and accept that most of what you say won’t be as good as your best material.
The brilliance of 37signals is that you saw the congruence. The mistake would be to believe that there is similar 1:1 correlations in most other endeavors. There isn’t.
Marc
on 06 Jan 12If only I didn’t work in a regulated industry (healthcare)...
It would be nice to only produce the documentation that was absolutely necessary, instead of mountains of docs that nobody will ever read, except the auditors.
Dan
on 06 Jan 12No spec? No product manager?
GeeIWonder
on 06 Jan 12Indeed. Nice piece of thinking.
One place where it gets tricky is the class of problems where the ‘one direction’ verges on the too hard though.
Mehtryx
on 06 Jan 12There are great points from the point of view of a designer with prototyping in mind.
However at somepoint your prototype gets off the bus and becomes a product, and at some point someone else is going to have to support, manage or add on to that product.
In those cases documentation is invaluable.
There is a fine line on too much documentation, obviously you should have the smarts to figure things out, and yet you should not need to read line by line source code to figure out what tables are in use, basic program flow, objectives of the code etc…
I think the real trick is to identify the point where the prototype moves to the next level, maybe its when you go from running local to pushing up to a provider like heroku, aws, etc.. really that is something we all need to identify when working on new projects.
The other thing to consider is that there is a difference between trying something for the “I wonder if this could work” and doing something to solve a business problem you know will be implemented. If you know in advance you are going to push something into production to solve an actual problem then documentation is something you should start early on, its less painful to provide the basics early rather than trying to wrap it all up after a few days (or weeks) of intense programming only to forget things.
As an integrator of solutions from dev’s who have built solutions, documented later and we full well knew these had to go to production…I can tell you many stories that included lines like “Well it works on my machine…not sure whats different…” that eventually end up in some library change, dependency forgotten, configuration or deploy step.
So yes again, agree….but only to the extent of new “what-if” code and only until you realize that it is going to be something more than a “what-if” or quick single use and abandoned solution (which is something I think should not happen either..but thats another topic).
Cheers
Dmitry Nikolaev
on 06 Jan 12Definitely, the article is more about process before documentation. Documentation, paper, help page, whatever… You also have the documentation. It everywhere, starting from first page of www.basecamphq.com.
There are two articles in this one. Second should named “How to produce design ideas”. Very grateful for sharing your process.
Scott
on 06 Jan 12Documentation is necessary because not every stakeholder properly understands what they should and not every cog is capable (or trusted) to accomplish their role.
In short, documentation is required because, at some point, a project will inevitably involve less than ideal humans.
The same dream world where no project requires documentation is the same one where, for example, no product requires a manual.
Nice thought though. takes (daily) red pill
Michael Z.
on 06 Jan 12Well, I have seen it several times. At the beginning we produce a lot of documentation, after we start developing the mismatch between documentation and the resulting product increases continuously and then we waste a lot of time in updating the documentation to what we have produced.
I think the best way is to start with a rough description of the vision, getting early feedback from customers working with prototypes and adjust the design documentation as required.
Daniel
on 06 Jan 12Basically, I think there are 2 kinds of documentation at play here: Documenting the product/deliverable, and documenting the process.
Documenting the process is the troublesome part, in my view. That’s what’s too often overdone, disrupts actual development, or what becomes an end in itself (e.g. CYA).
However, much depends on the company you’re in, and the culture there. In a big company, a lot of time is often wasted going down the same development dead ends as some other team (or re-inventing the same solutions) because that other team either didn’t document it, documented it badly, or left behind too much documentation for anyone to learn from. Or maybe they left behind just the right documentation, but the company has no tradition or system for passing such knowledge around.
So the issue isn’t really the documentation itself, as much as its context, use, and purpose.
Ryan
on 06 Jan 12Seth said:
It’s not a happy accident—it’s a choice available to people working in our domain. There is a whole class of applications where a bottleneck in throughput evidences inefficiency: those where the UI layers and the backend layers are symmetrical in complexity. I distinguished this “layer cake” kind of product from “iceberg” projects in Visualizing a product’s UI and code layers.
While I don’t claim our situation is universal, it certainly does apply to lots of people developing software in the same class.
Brett Atkin
on 06 Jan 12I understand where you’re coming from but I don’t think you’re being realistic. You live in a world where you’re not dealing with clients and don’t have to worry about the numbers matching up (what you quoted with what it actually took to create).
As somebody mentioned, documentation is for covering your ass (CYA), but it is also for defining the deliverables (and payment) as well as a cut off point between what is in scope and what isn’t. We create all that documentation (AI’s, wireframes, flow-charts, graphic mock-ups, etc.) so that we can get sign off from the client as well as have a defined plan for creating the application.
Are you suggesting that if Jason and David decided to build a better Campaign Monitor you wouldn’t sit down and work out the navigation structure, create a few wireframes and design comps and most importantly, create a list of all required / nice to have functionality?
Ryan
on 06 Jan 12Brett,
Yeah, if I were consulting today I would try to work in short increments (x weeks) at a fixed price per increment with scope as the variable.
I can’t honestly promise a design will have certain attributes until after it’s designed. Otherwise the time spent wasn’t design – it was implementation. The only way I know to address that conundrum is to reduce the up-front risk by working in smaller increments, promise less about the specific form of the solution, and consistently deliver impressive and faster-than-expected results to build trust along the way.
Kimberley Dietemann
on 06 Jan 12Clients care about work that they believe will provide value. Only hiring designers who code means that you may not hire the kind of designer who can clearly articulate why anybody should care about the other aspects of creating a desirable product.
To me, the purpose of those artifacts is not to kill hours of everyone’s time with a bureaucratic process. It’s for testing with the people who will be using the product. Releasing live features to generate feedback isn’t always quicker than doing some quick tests with a random person, a piece of graph paper, and a pencil.
Implementing an idea and skipping that whole boring research / testing process seems more efficient. Clients will rarely complain. They want a shiny deliverable and they got it.
Many talented programmers can turn around changes so rapidly that they don’t think it makes sense to waste a ton of time testing everything in advance. But that kind of testing doesn’t need to take a lot of time. Avoiding it is the equivalent of throwing darts randomly at a wall when a book is sitting next to you titled “how to hit the target”.
Its value isn’t immediately apparent. If a journalist interviews someone poorly and misses crucial information, the person they’re interviewing may not know. The journalist may not know. Their audience may not know. Everything seems fine.
But we know when something is really, really, really wonderful. Many good, successful products come from companies driven by engineers and developers (Google, Amazon, etc.) But a product which is truly amazing does not originate in a culture that devalues all work beyond immediate implementation.
(This isn’t a comment about 37signals products, btw… more a general rant about the philosophy that the fastest way to test an idea is to implement it. Sometimes that’s true… but definitely not always.)
Harry
on 06 Jan 12Seth, I believe Christopher Alexander (the architect) would disagree with you. You’re observing the current process. If you change the process, you change the rules. Isn’t that part of what you teach in your books and your blog?
The current process of building a skyscraper, even a house, proceeds as you describe. But if you change the process of building you’re no longer under the old constraints and you can produce better (living) buildings, better neighborhoods, better cities, and ultimately a better world. Alexander’s The Nature of Order series is highly recommended reading in this area.
The key point I take from Ryan’s article, and indeed, many of the 37s blog posts, books, and such, is not that you must also do it this way. It’s that you should observe your process, whatever it is, scrutinize it, and see if you can do away with some unnecessary part of it, or change the process altogether.
Many people believe that documentation is an essential part of creating something, but 37s has supporting evidence to prove that this is not necessarily so. And that should cause us to reflect on our own processes.
G.Irish
on 06 Jan 12@Kimbereley I think you hit the nail on the head. Using paper and a pencil to document something is a lot cheaper and faster than writing up some code to meet a customer request that may not have been fully baked.
What I’ve found is that it is much easier to uncover errors in logic, misunderstandings, and omissions by documenting things and reviewing them with the customer before implementing them. This becomes even more important as the complexity of the software increases.
Sure you can get away with very little documentation on software projects that have a small number of features and don’t interface with anything complex. But as soon as you start piling on use cases and complexity, coding and redoing prototypes can quickly turn into a development black hole.
Jason Carroll
on 06 Jan 12Well said Dmitry!
We should all be focused on building the best products, but oftentimes people become fixated on documenting the best product.
When we start digital prototyping with clients, they immediately understand the power of quickly iterating to design a solution. It literally brings abstract ideas to life.
Some enterprise clients need written documentation in order to maintain and expand the systems. For them we create a hybrid (“enhanced requirements”) where the prototype demonstrates the majority of the requirements (WYSIWYG) and the written documentation covers technical architecture and the things that can’t be seen. It gives everyone the best of both worlds.
Doh
on 06 Jan 12@37signals
You guys really need to add the disclaimer to each of your blog post “This works for us, results may vary”.
Because it’s obvious time and time again, that many of these thing work solely for 37signals because you guys focus on solving unbelievably simple problems.
Tim Daly
on 07 Jan 12This is a great approach if you plan to throw away your work. But if your company (or your clients) have code that is vital to the functioning of their company then you’re making a grave mistake.
I worked on a project for years. We documented nothing. The project was sold commercially and withdrawn from the market in 2000. I got permission to open source it. So 10 years after I wrote code I got my own code back. It was an interesting experience.
I write dirt simple code. I could read the code and I could tell you exactly what every routine did. But the whole project was nearly a million lines of code and I couldn’t tell you WHY I wrote the routine. I knew it was vital as the system crashed without it. But I had to reverse engineer WHY it was needed.
So if you are doing code that has to “live” and have customers who depend on the code, you are throwing away the most vital piece of information. It’s like taking a calculus textbook, extracting all of the equations into little files, and throwing away the text.
Use literate programming. Have several paragraphs for each routine. Review the paragraphs in code reviews before every checkin. There are 3 effects you will discover:
1) The original programmer will make fewer mistakes and catch more mistakes before review 2) The review team will give better reviews and higher quality code will result 3) The customer will be able to hire people to maintain and modify the code even though the original authors are dead. In short, the code will “live”.
Professional programmers don’t “dump and run”. Write code to survive the original authors. Write quality code that can be read and understood by non-team members. Communicate the ideas to humans and, as a side effect, to the machine.
Literate programming.
Tim Daly
Jonathan
on 07 Jan 12I can see how this approach can work for business software applications, where the interface doesn’t really heavily on graphic design. In my opinion, Basecamp fits in this category.
Please don’t get me wrong, I use Basecamp a lot and like using it, but it isn’t a work of art when it comes to its presentation. There is certainly a lot of design going on, but little in terms of graphic design.
This is very different from client facing projects, where these documents are still very useful as Brett points out. I doubt that clients will sign off on a project done incrementally. When they come to you, they usually have a rough idea of what they need, and they want to launch the new thing with marketing actions, meaning you can’t add features one by one.
Also when you look at a typical web project, programming is usually the most time consuming. It makes no sense to pay programmers to code a feature and than going back and change it. Things need to be sketched out, planned, coded and deployed with no going back to save money.
The same applies to front-end development. Cutting up PSD files and translating the design into code is pretty time consuming, so doing design iterations in code makes little sense, although static pages are a much better representation of the finished product than mockups.
But flow diagrams and mockups serve a purpose, they give the programmer (and the customer!) an idea of what the finished product should be, so that he can write the appropriate code.
And as Tim points out, documenting your code is very important, especially in the web world, where people often change jobs and projects are handed off to people constantly. This is where technical documentation comes into play, before starting to code and after having finished your code.
We should also not forget that spending time on making a product visually pleasing (via mockups) can make or break it. I worked on an application which is very useful to customers (they can book appointments via a website and don’t have to phone in), but it rarely gets used because when we attacked this part of the project there was no budget for design work left, so now the things is as ugly as Excel and also nearly as fun to use as Excel.
Michael
on 07 Jan 12I realize 37signals’ products’ source code isn’t public. But one only needs to look at api.rubyonrails.org and several other public repositories maintained by 37signals employees to see that “no documentation” certainly does not mean the code is inscrutable or difficult to understand.
Michael
on 07 Jan 12Just to clarify, ‘no documentation’ doesn’t even mean literally no source code documentation. It just means the entire layer of superfluous documentation layers is scrubbed off because it’s not consulted. The consulted documentation remains.
Morris
on 08 Jan 12You guys are full of sh#t.
IT Rush
on 08 Jan 12Moving in one direction in one feedback cycle is easy. Moving in ten directions in the same cycle is too hard. I love it.
Kenny Sabarese
on 08 Jan 12I assume you are only talking about documentation in regards to development and not support or operations?
Johan Strandell
on 08 Jan 12I agree about the basic premise, and I’m trying to move in the direction of minimising documention myself. That said, I think there are situations where documentation has a purpose:
1) As an overall plan – if you’re creating a new product or building something complex, some kind of documentation of the bigger idea is needed. Designing everything piecemeal often ends up in an unstructured mess, or you forget parts, in my experience. (This especially so if the developers are not the users of the product.)
2) As documentation for others – consultants usually don’t take part in the whole lifetime of a project, and without documentation it’s harder for others to understand the rationale behind a design.
A prototype or finished implementation can have a lot of thoughtful design behind it that’s not obvious for those who use it or are expected to continue developing the product in the future.
(Also, the CYA aspect mentioned by others above.)
3) As a way to handle the workload – many companies I’ve seen have a ratio of 1 designer per 100 developers or thereabouts. Then it’s simply not feasible to have designers work closely on the code – it’s much faster to produce wireframes or other design deliverables.
So I’m all for the workflow described in the post, but I think it requires much more than what might be obvious from the post. (I.e. a team working on something they know intimately and use themselves, a product that has a structure in place, designers with knowledge of the technology being used and few developers per designer.)
I.Adam
on 09 Jan 12Documentation is a must. But it should not be only to document. It must be helpful.
Andrea at ProtoShare
on 10 Jan 12Having experience in client work, I believe documentation is important – but it should be more than just dense words. It can be wireframes or a prototype to visually portray what it is that will be built. And as others have mentioned, it is used to validate understanding an approval by clients (or team members).
On the other hand, as another commenter mentioned, building prototypes in code is expensive and can be a development “black hole”, so there is a fine balance to how much documentation you should create.
Our founder, wrote a post in response to Ryan’s article as it hits close to home for us and our customers.
TVD
on 11 Jan 12Documentation is Dead on Arrival (D.O.A.). If the project can’t survive on the sanctity of your code base, then you’re just doing it wrong. The UI…The End Results…The How Your User Feels…Those are all that should matter. Those are all that do matter. Always be shipping!
Martin Davis
on 11 Jan 12Ryan: You have done an excellent job of summing up the documentation dilemna. What management solutions + techniques can you suggest for an industry that has no choice (legally) about documenting many items?
For all of those referencing architects as an example, the earliest known documentation of a building is minimal on details because architects and builders worked together at the time. The industry is suffering now because of liability and blame games.
Christopher Alexander is certainly an interesting example, however, his methods do have limits (3 stories). As many have pointed out, there will be a time when you have to document because of the complexity.
mywork
on 12 Jan 12i think its ok
Ryan
on 12 Jan 12I would have to hear more about the specific problem I think, because I don’t have experience with that. (Feel free to email ryan at 37signals.com).
Generally I would inspect the role that documentation is playing. In the article I argued against using documents as a way to freeze design knowledge so that implementors can later thaw and apply it. That position doesn’t preclude you from producing documentation to record decisions or from making checklists to ensure that legal requirements are factored in as constraints. The difference is in whether the documents are driving the design process or if they are coming out of the design process as byproducts for accountability, history, etc.
Tracey
on 13 Jan 12My thoughts on why we at Fastspot think documentation IS important are posted here – http://www.thinkdesigninteract.com/usability/why-documentation-is-important/ Interesting topic to discuss, particularly where the boundaries exist between software dev and client services.
This discussion is closed.