We write code, not documents

Recently a student asked me:

Could you describe one instance where you had to use a diagramming tool (eg. Google Slides Drawings, Lucidcharts, Miro, Whimsical, Gliffy etc) to accomplish a task?

They also provided an example answer I could follow, which consisted of creating a chart to map a user flow, presenting it, getting feedback, adding it to another larger document, and creating Jira tickets.

I was a little surprised (though simultaneously not surprised) — is this how software development is still being taught?

Without being critical of academia, this seemed like a good opportunity to try to shatter by-the-book software development ideas for some future engineers by sharing a different way — our way.

Here was my answer (slightly edited for clarity and typos):

I hope this answer is helpful, but I actually don’t use a lot of diagramming tools, and I think it’s safe to say they’re not commonly used at Basecamp. We don’t write specs and stuff like that as they’re not “real” enough. We will do high level sketches and rough drawings (usually pen and paper or an iPad and a sketching app), but that’s typically it. So more often I’ll grab a pen and paper and sketch out a rough flow of what I need to do, or write out pseudo code of the steps that I need to take. 

The reason we don’t get too formal about diagramming is because they’re often not close enough to reality. You can draw and draw, but the reality is until you start writing some code or implementing a design, you don’t know what you’re going to hit. Maybe you’ll hit a technical limitation or maybe something just flat out doesn’t work. All the diagrams in the world don’t get you closer to finding out that stuff. So the sooner you get to real code, the sooner you‘ll get to seeing what’s possible. Fast and iterative in real code is where you want to be, not locked into a document.

With regards to frequency, I’d say I do that about every day. Because it’s so lightweight, there’s no barrier to entry. I’ll draw out what I need to do or write out the steps and then get to it. Very often I’ll hit something unexpected and then redraw what I need to do. It’s fast and iterative, and nothing is written in stone (because in software nothing is ever written in stone!)

Whether you agree or disagree with our way of software development, it’s an honest assessment of how we’ve done things at Basecamp for a long time. And I’d say all things being equal, it’s worked out pretty well for us. 😉

21 thoughts on “We write code, not documents

  1. I rail constantly against the “wireframes” members of my team develop that are high-fidelity mock-ups of some finished UI they want to see. More often than not, their idea of how a feature will be implemented is counter to how I’ll end up coding it and I have to fight stakeholders who think the original design was some kind of requirement.

    1. If you’re shipping a consumer product, shouldn’t the UI design drive the code? The designer’s job is to test and validate the UI so that it makes the most sense to the user, not to the engineer. How you’ll end up coding it is transparent.

      I think this article is referring to the unnecessary steps of excessively diagramming every little engineering tasks. But if we’re talking about entire products with many user-facing states, some blueprint is critical to a coherent and intuitive end-user experience in my opinion.

    2. Donny, the issue is that a high fidelity mockup will look more opinionated than the designer intended. As a small example, a designer might want a magnifying glass for a search icon, and will quickly grab one from an icon set that turns out not to match the icon set being used on the site. The designer didn’t mean to force programming to use a new icon set, but the high fidelity mockup creates the impression that the specific icon is desired, and now QA will make the code match which results in unnecessary new assets being loaded. Small things like this are constantly a risk when the mockup looks polished and opinionated.

  2. Some diagrams are helpful. We tend to use some tools to show complex network interactions like those needed for un/pw authentication sequences under OAuth.

    And in response to Peter’s comment above: Are you a UI/UX designer? In our shop the original design was approved by the stakeholders and it IS a requirement.

    If there’s a technical reason why it needs to be different and if that reason results in a better user experience then we can change it, but changing it just because I might want to code it differently isn’t a valid excuse.

    1. Technical limitations and easier-to-code approach aside, one can imagine how wireframes (leave alone polished mockups) can end up inadequate because designers thought of the happy path and ignored possible edge cases. This is where UI flows may come in handy.

      Or they might not, because it’s often the case that the edge cases only come up during implementation. Whether it’s bad or merely normal, I don’t know. Some claim that thinking them through in advance is a boon, starting with, I don’t know, Joel Spolsky: https://www.joelonsoftware.com/2000/10/02/painless-functional-specifications-part-1-why-bother/

  3. I find diagramming tools really useful, but only as a lightweight check to make sure everyone’s on the same page. When I’m working with a designer, I’ll frequently sketch possible states out in graphviz or sketch.systems to illustrate the possible high-level states the system could get into.

    Thanks to Hillel Wayne, I also recently learned about decision tables (and their sibling, state-transition tables) which are also great for clarifying intent and finding holes in our thinking!

  4. If you’re not diagramming, you are not building something sufficiently complex that models some process complexity.

    Imagine building a house or sky scraper without a blueprint and stacks upon stacks of diagrams both informal and formal. A house is a complex structure where mistakes can compromise the structure and safety of the occupants. Scale that up to a skyscraper and you’re talking diagrams that can mean the difference between life and death.

    No one is going to lose millions of dollars if Basecamp fails. High speed trading systems, systems which support critical manufacturing processes, systems which support regulated industries: you’re talking about millions of dollars or safety at stake when mistakes are made which could have been designed out.

    Your students have the right mindset: do it right. Convey your idea. Discuss the idea before writing the code. Gregor Hohpe formerly of Google Cloud has some great writing on this and how valuable diagrams are for communicating complex ideas.

    1. This idea that we don’t need diagrams to help communicate ideas just seems to be an asinine conclusion to boast about; of all the things to be proud of “I don’t draw my ideas” is just…I don’t know, a weird one to pound your chest about.

      When I request a quote for a new patio, the landscape architect draws a diagram of the patio to ensure that it’s what I want. The diagram is submitted to the township for approval to ensure that it meets building codes. The diagram is used to calculate the material needed and estimate the cost of both material and labor.

      When studios make movies, the starts from a screenplay and a story board. Even animated movies start from a rough design and sketches committed to paper.

      “But this is software!”

      It doesn’t change. I have worked with enterprise customers from Northrup Grumman to Novo Nordisk to Citibank. I have been a consultant and a part of multiple product development teams. The point of the diagram and design is to make sure that all teams are talking about the same thing and that we do it right the first time. We have been diagramming since our cave dwelling days because it is such an effective way of communicating.

      The point of the diagram is to ensure that we’re all communicating on the same page and assigning the same meaning to the words we are using the convey our ideas rather than doing it twice or three times or more.

  5. I’m with Charles Chen on this. If it’s a simple process, then a back of napkin diagram or no diagram and just jump into code works.

    That ain’t gonna fly if you’re dealing with serious healthcare applications where the complexity of the algorithm (eg. virtual crossmatch for organ transplant tissue matching) is off the charts and you’re also breaking new ground on how the algorithm should work. Especially if the process has no visual UI component that can be easily seen.

    In that case, creating diagrams to discuss with experts (SMEs) to validate new algorithms, identify edge cases, and create a spec that is implementable in code is a “good thing(tm)”.

    And in healthcare, may even save some lives than just hacking away at some code.

    1. Basecamp people don’t make complicated or mission-critical software. So they get to brag about nonsense like this. It makes them look rather silly, to be honest.

  6. Nothing against Basecamp, it’s extremely useful software, but this approach works because it’s a simple system with a focus on UX. The company I work for has around 2,000 UI and middleware applications that share data with each other and tens of thousands of mainframe processes. We can spitball ideas and discuss options with our user base over paper and whiteboards, but managing those without a formal, visual record would be a nightmare.

    Dan has a great point about diagrams often misrepresenting what actually gets implemented. We battle this all the time. The first time you make a change and forget to update documentation you’re in trouble. We’ve tried different ways of auto-generating diagrams from code and it works somewhat but it’s far from perfect. There is not a blanket answer that works for all systems or organizations and like most things in design I think the answer for any given scenario is “it depends.”

  7. I think the disagreement in the comments probably has more to do with “client” work vs. “product” work, than software development process in general.

  8. You seem to be contradicting yourself. The title says, “We write code, not documents” but you describe a process that involves daily diagramming—on a physical piece of paper albeit.

    Correct me if I’m wrong, but your argument seems to be more about the medium in which you should diagram and the process rather than whether or not you should diagram at all.

    I agree that diagramming cannot completely encapsulate a software system (“All the diagrams in the world don’t get you closer to finding out that stuff.”). And I also agree that most diagramming should be fast, cheap, and iterative. But pen and paper are not the only ways to do that.

    Where I work, we create PlantUML diagrams. I can create a simple PlantUML diagram in seconds. In addition, once that diagram is completed, I can commit it to a GitHub repo. Once it’s in the repo, any developer in my organization can edit the code and regenerate the diagram. It’s not only fast but the iteration history is improved.

    I agree with your core argument—create fast iterable diagrams. But there are more ways than one to accomplish that.

    1. I was about to bring up PlantUML as well. I fully agree with tools must be lightweight and make it easy to modify collaborate. For me is pen & paper, whiteboard, ipad + pen and plantUML.

      However PlantUML is a level of polish that takes more effort that all the former tools. Most of the time we don’t need that level of polish & formality. I only use it if I have to create shared understanding of detailed technical flows with several teams. Which happens on a semi regular basis because my company is large (~20k employees).

      In the past I worked in smaller organizations (<100 people) and I never, honestly never needed such detailed diagrams. A whiteboard discussion or sketching out code or pair programming always sufficed.

  9. We don’t do detailed designs and diagrams either. They are high level at best. But we do use writing for describing what features should do. I learned that writing is the best tool for, at least for me, to design features. It provides context for the developer and helps me rethink how a feature should work. Some people call them user stories, but I don’t like jargon and just call them short descriptions :).

  10. I am working on a project where there should be a database redesign. The current database has so many problems that it may be a threat to my client’s ability to scale.

    Before there can be a database redesign, the data that will be stored in the database must be documented so that a new schema can be designed. The data cannot be easily inferred from the existing database because the structure is so complicated that only a few people understand it.

    A database redesign will impact a significant portion of the existing software. This kind of change needs to be carefully designed. Without careful design there is a danger that the new database will be no better than the current database.

    The idea that there should never be careful “up front design” is one of the more misguided things to come out of the Extreme Programming and Agile movement. As others have noted, would you build a multi-story concrete and steel building without doing “up front design”?

    1. I totally agree that designing ahead of time is useful and often necessary. But up front design is not the same as high polish diagrams.
      In particular a database schema can be represented more lightweight in the DDL native to the database or tables in a wiki, no?
      Or to ask from the another angle: what aspects of the database schema and migration require high polish diagramming?

      And I have to say: The way I understand the post Dan didn’t say anything against up front design. (Neither does XP as described in Kent Beck’s book imho).

  11. We approach software in a similar way. We don’t really use diagrams or diagramming for the sake of it. It’s all about the tool that we pick up for the job. Sometimes a diagram works, sometimes a sketch works, sometimes annotations works, sometimes a long form of write up works. When I worked in some large sized software, I diagramed things myself like a simple CRC card to decode the components. So whatever works!

  12. I’ve worked on projects where the design doc became the god, before any code was written. There was often insufficient time left to write the code, because so much time was spent writing and re-writing a holy document. I always preferred the engineering approach, where we could show some results quickly, because this always exposed new requirements.

    Specs and UI features changed all through this period but somehow the deadline never moved. You’re left wondering how we work this way, and why.

Comments are closed.