On Breaking Down Larger Projects

A Meditation on a Question Often Asked of Me

Recently in two different mentoring sessions, folks have expressed an interest in getting better at architecture and breaking down larger concepts. In other sessions of years past, folks had similar concerns.

This desire to break things down into their an atomic structure is an interesting desire. We wish to name things; to give them concretion such that we have dominion over them.

And you’ll notice I struck out “their” and replaced it with “an”; it is presumptuous to think that we can break something conceptual down to it’s atomic level. It presuposes that we understand the atomic level of concepts.

But I’d argue that we’re interacting with concepts that fundamental delve below the Planck threshold.

This afternoon it dawned on me that I haven’t had to do much of that recently; instead I’m relying on past experience from prior projects.

However, I want to use this time to think and synthesize.

A Personal Philosophy and Strategies of Work Breakdown

When I think about the larger projects I’ve architected, they invariably involve working with data. Let’s describe some of these projects:

  1. An online site that allowed users to upload address books and to create schedules for sending out personalized cards to a subset of the address book. Those personalized cards were part of the catalog of cards; each card had constraints (e.g. 2 lines of personal text or 3 lines).
  2. An online collaborative workflow tool that helped folks route a digital object through the numerous handoffs of approval.
  3. A batch process to generate insurance documents from multiple temporal axises.

And as I look back to those projects I think about the work I’m doing now to trial a migration from Org-Roam 📖 to Denote. First in Exploring the Denote Emacs Package, then in Migration Plan for Org-Roam Notes to Denote, and in my pending Denote Emacs Configuration.

  • What is the data structure “at rest”?
  • What is the data structure “in motion”?
  • What are we exposing to the various people interacting with the system?
  • What and how are we allowing folks to change the data?
  • What are we showing them?

To understand the data structures one must understand the problems folks are trying to solve. And in my experience folks often come with ideas that they parade as problems.

Which introduces my first bit of advice: to understand how to break something down, first make sure you understand it. Spend time clarifying and asking questions. Seek the problem that lies at the center of all the ideas.

Invariably this will lead to conversations; my recent writing is conversations with myself. Most of it related to working with computers. One variety is knowledge sharing; for example Public and Private APIs versus Public and Private Methods. Another variety is thinking in the open; Analyzing Rails Application Code to Consider for Extraction into a Gem.

Which introduces my next bit of advice: to break it down, write it down.

In one of my recent tasks, I started coding a solution thinking first of technical symmetry. When the time came to write the commit message, I invoked two phrases that I find most helpful in commit messages: “Before this change…” and “After this change…”

In taking time to write the “After this change” section I realized I had solved for technical symmetry instead of the production problem. I did not scrap the work but continued writing the commit message as a letter to my future self; namely using that scrap piece of paper as my moment to break things down.

I committed that change and left it on my local machine. I noted the commit in my todo items for the next day, and when the time came I referenced that approach and turned around the code.

Which introduces my next bit of advice: with all of this digital writing, take the thinking out of where you’ll put it.

Accept that you are going to write notes in places where they might not belong. Just keep writing. Don’t think about where it goes until you are done writing it; in other words don’t solve two problems at the same decision point.

With my current work setup, I can quickly capture a note to a project or a general todo item. I then start writing. When I’m done it’s in a spot I’ll likely notice. And if I need to I’ll move it to a better location.

This document, for example, began it’s life as a to-do item in my mentoring session notes. I moved it to my general todo list and started writing. I then realized it was becoming a blog post. So I moved it to that file.

Along the way, I created links from the original location to it’s successor location.

Which introduces my next bit of advice: software is by it’s name soft and malleable, assume your information about it will be so as well.

Taking the time to write things down helps me remember, both in my brain, and through various search tools; thumbing through a paper notebook or searching through a file system.

But writing down is not enough, you need to revisit that and organize it. If I find a project getting “conceptually large”, I create an index page and make it prominent. An example, with a twist, is that my day to day work is a complex project. I start and stop tasks, jump to and from code, and track my time.

I have an index page, my agenda.org file, that I leverage extensively. It helps me find my way on the project that is my work day.

Now, with all of that I feel as though I’ve gone a bit afield of the question; how to break things down.

But at a meta-level I believe this post addresses that as well. Namely meander through the space you’re exploring.

Give things names, both the “data at rest” (e.g. the noun-type things) and the “data in motion” (e.g. the verb-type things). Draw some diagrams to connect those concepts. Don’t worry about getting everything or all of it correct or in proper Unified Modeling Language (UML 📖) notation.

In one group session for breaking things down I suggested (or ratified the suggestion of) the word “Wortem” to sit as a proxy for the disagreement we had regarding calling something a Work or an Item.

To this day, I smile and think of the friends and colleague with whom I could slyly nod to and whisper “Wortem” and invoke a wave of memories.

Be verbose in those names but hold them lightly; consider how hard it would be to rename that thing once you’ve introduced it into the larger context.

Instead draw as another way to explore the problem space.

Which leads to the last bit of advice: play is a powerful mechanism for learning, don’t forget to do it.

Step away from the problem you’re exploring and let it breath.

While sitting at a table at a farmers market, I developed the first pass of the database tables for a complex project. My brain was figuring out the problem and in that moment erupted with the proposed solution. I scribbled it on a notebook, tucked it into my backpack, and took it to work the following Monday.

Summary of Phrases

Here are my philosophical reflective phrases on breaking things down:

  • To understand how to break something down, first make sure you understand it.
  • To break it down, write it down.
  • With all of this digital writing, take the thinking out of where you’ll put it.
  • Software is by it’s name soft and malleable, assume your information about it will be so as well.
  • Meander through the space you’re exploring.
  • Play is a powerful mechanism for learning, don’t forget to do it.

Overlaying Additional Advice

I wrote the above . I had additional insights. And they touch on Stephen Covey’s oft, and rightly, quoted phrase: “Start with the end in mind.”

Having clarified the problem and perhaps being equipped with some ideas of it’s solution; what does the end results look like?

Be specific, yet not too specific, about the human facing interfaces (e.g. web pages and forms) and data flow.

For example, “A person using this feature will be able to go to a page in their account, and select from one of three options. Once saved those options will alter the format of their default search results.”

The size of that feature is irrelevant; some might consider it large and others small.

Next, start picking at the “end state” with a question I like to ask to help get something unstuck: “What would need to be true for this to work?”

What would need to be true for them to select options? We would need:

  • a route to get them to the options page for their account
  • a page that has the three options
  • a route to notify the server of the updated form options
  • a place to persist this option
  • adjusting the search result rendering logic

That’s the happy path. Now look with the pessimistic lens. How could this all go wrong?

  • One person attempts to go to another person’s configuration
  • One person adjusts the HTML form to include an invalid option
  • We remove one of the configured options
  • Someone unsets their choice
  • Someone never set their choice
  • And so on

Don’t dwell on the negative, but do give it some thought; because only writing for the happy path is naive.

As you look at the above list of what needs to be true, if any of those items are not already true, re-state the question for that item.

You do not need to solve how to make it true; you need to say “When this item is true, we have a piece of our solution.”

Conclusion

As with all advice consider the giver of the advice. All of what I’ve mentioned, I’ve used as a strategy for breaking down complex tasks.

I don’t think at any point I’ve used all of them at once. I’m also quite certain that I haven’t adequately plumbed my subconcious to tease out all the tricks it uses to break down tasks.

Which is to say, a great way to learn is to do it. Ask to lead a work breakdown with the caveat that you want to schedule time to go over the results; not at the end of the project but before anyone get’s to say the breakdown is done.

In other words, play with it.