The 5-minute Journal

Last year I bought, in some sort of moment of defeat against the capitalism of productivity tools, a product called The 5 Minute Journal after hearing a few people talk about it.

(Important note: since I bought it the creators have created the following video which would have made me not buy it if I had seen it before, probably due to my overwhelming jealousy. Who in Oden’s name gets to wake up like this?)

The product is meant to increase mindfulness and focus. The idea is pretty simple – you spend a few minutes answering the following every day:


I am grateful for ____ [3 things].

I am grateful for ____ [3 things].

What would make today great?  [3 things]

Daily affirmations.  I am… [2 blank lines]


3 Amazing Things that happened today… [3 things]

How could I have made today better?

2016-04-20 08.51.25

I bought the physical product and wrote in it, but they now have an iOS app.

Actual Science

The exact questions are based on positive psychology and the work of Dr. Martin Seligman (author of Authentic Happiness, Learned Optimism, and Flourish).  In his research, he has shown that remembering positive events, expressing gratitude, and focusing on our core strengths and help people climb out of depression.  I knew none of this when I bought this book; I simply heard Tim Ferris say it was cool and if you listen to enough Tim Ferris eventually you will try something he is trying.

My experience

First, I was surprised at how many times I forgot to do it at night. Apparently in the morning I have a very complex “getting started” ritual and an “end working” ritual, but no “going to bed ritual”. My getting started ritual always happens at my desk, but the good night ritual happens upstairs so I never saw the book to remind me to do something.

Once I established it as a habit it was very interesting to see what I put in there for goals and positive outlooks. An important detail to note is that during the time [sprint 2015] I was using it school ended for my kids, and both my wife and I tweaked our back (separately) and started going to physical therapy. It was at times very frustrating as health issues often are – I would feel better and then she would feel worse, and all the kids being around didn’t always help either of us rest.  It was a frustrating time and you can see this reflected in the journal. Rather than just being down about my back I would say things to it like “What would make a good day?” and I would put stuff like My back is the same, and my wife’s is a little better and I would have to say that to myself a few times – define the day-by-day by that criteria.  At the end of the day I would have to write that, in fact, our backs were the same or a little better and forced myself to define the day as a win.


I could see this tool helping you to change the way you think slowly over time, especially with large goals. If you are looking to get into college telling yourself a few more times a day will not hurt you and will help you stay focused on that goal. And the “end of the day” items were very interesting – you dream about things you are worried or anxious or have just thought about, so a positive reflection on your day is and effective routine before you go to bed. It simply works.

I struggled to know what to put in the “Daily Affirmations” box. Struggling to figure out what I would put there made me end up putting a goal in there “working towards X” or a reminder of a core strength “good at coming up with ideas”. I never knew that a small book could turn me into Stuart Smalley but here we were.


Another thing that is obvious but made me feel good is that at the end of the day it served as a way to remember good things that happened. One of my implicit life goals is to hold my temper and be patient with my children. They do not share this goal, but I found myself simply writing down “did not yell at kids” or “good day with kids” or “0 tantrums from anyone” day after day and realized that things were going pretty well. And reminding yourself that things are overall going pretty well is a very powerful idea.  And the real revelation with this journal is that there were times when I wrote things I never would have expected like “nice sunset tonight”.

Chaos-Proof Your Marriage with Monkeys

The best thing that happened to our marriage is my wife getting so sick that she couldn’t walk down the stairs more than a few times a week. She was pregnant with twins and was having a side-effect of having hives all day and feeling sick. We saw a large number of doctors about it and learned how all of them looked when they had no idea what to do.

She was upstairs for seven months (the whole of the pregnancy), and I had two daughters to take care of: get to school, feed, clothe, argue with, etc. I did this in my standard fashion for a few weeks, and then things started to fall over.

First, we ran out of milk. Then ketchup. Running out of ketchup is like a methadone clinic running out of methadone. Then toilet paper.  The girls wanted to talk to me about things that I didn’t normally talk to them about.  The house needed to be cleaned.  The fridge and pantry became empty at a disturbing rate.

Also, I started to notice that I didn’t have anyone to back me up. I had to read and sign all the kid’s papers and clean out the van every few weeks, answer *all* of the mail, go to parent/teacher conferences, and have sad, hard conversations with kids that wanted to talk.

I was a single Dad during this time, and it made me a much better parent. Before my wife got sick I was a “bench player” and she was the star when it came to running the household and taking care of the kids. I backed her up and provided all the help I thought I could give, but I stopped short of full and complete responsibility for those areas. That stunk.

That stunk for her because it meant that she didn’t have an equal partner that was thinking about this stuff all the time and could provide ideas and stress relief. It meant that she lived with someone that didn’t know how difficult it truly was to take care of kids all day and be tightly-wound at night.

There is this idea championed by the Netflix organization that says that you should plan for chaos by creating it. The infrastructure to run Netflix, which during the holidays is 37% of overall Internet traffic (ugh) in North America, is as you can imagine vast and complex. They are leaders in providing always-on services, and many in my industry learn from their experience.

They use a piece of software called Chaos Monkey to test the fault-tolerance of their systems. You can imagine chaos monkey as a sub-system that randomly stops and messes with other parts of the infrastructure. If Netflix is a large room full of computers Chaos Monkey is acting like a literal monkey and unplugging, chewing through, and pissing on all the computers. And their software is disabling those computers and restoring power and firing alarms as these things are happening.

Overall, because of the chaos, they are much stronger.

My marriage had a very common anti-pattern to it: the less-involved husband. The extreme of this idea is the husband that comes in and grabs a beer and starts watching TV as his wife tries to cook while kids hang onto her feet. The most typical version of this is a husband that stops short of full responsibility when it comes to making decisions around the kids:

“Well, honey if this what you think is best.”
“I dunno what does the teacher think.”
“Sweetheart I’m too tired to think about this from my long day of (insert something that isn’t that hard here), can’t you just decide without me?”
“Talk to your mother.”

I can still be like this, but I know recognize it and try to push through and be better for her, for the family. And whenever more chaos arrives: sick children, family struggles, etc. I try to take it on directly and learn from it.

And, of course, this experience has taught me to appreciate my wife and all that she does.  There was so much “dark matter” of activities that I never saw that she did to keep things running.  I knew of some of it through weekends, but I didn’t appreciate how much work it was to buy vegetables on a Tuesday afternoon to save some money, or to keep an eye out for summer camps that were good for the kids.

If you learn from every struggle and approach every struggle with this attitude, then you end up being much stronger.  Because if there is one sure thing in life it is: you will have struggles.  Even if they aren’t literal monkeys pissing on your computers.

Sacred Space: Building the Energy of your Home Office

In a previous entry I mentioned that you should have certain infrastructure readily-available when you work from home. After I wrote it this idea kept bouncing around my head that is a lot more important: how you treat your home office.

What you don’t do in your home office and what you don’t have in there matters more. You can’t just pull up a fold-up chair to a coffee table and get real work done over the long-term from home. You have to create a Sacred Space.


To pull off working alone and to build anything of any real value you should treat yourself as a professional and respect your work for its intrinsic value. Take it seriously and build a space that shows this attitude.

Don’t eat at your desk. Don’t browse YouTube aimlessly at your desk. Take a break at a separate desk or computer; the space for work is for work only. Don’t allow your kids into your office unless they are there to make something. When they make something put it up on the wall. The smell, energy, and feel of the place is that of doing stuff, making stuff. It helps your muscle memory when a space is always used for the same purpose.

This of course means that you probably won’t be sitting at your desk for 8 hours a day. The time you aren’t working you shouldn’t be in there. Run your online errands elsewhere; check your news elsewhere.

Design your space

Your office should be highly-functional but pleasant. You should be in  direct control of noise and interruptions as much as possible (door that shuts is a minimum, steel door that shuts is better, sound-dampening room with a parachute catapult for quick exits is ideal).

Your office should be treated seriously but it should be a place that you want to spend time. Work is hard sometimes. When you look up from your computer to think  you should enjoy the fact that you don’t have to look at sad greyish-brown-really-man-oh-man cubicle walls or generic ‘art’ and the smell of sad coffee stains soaked into the walls of a typical office space. Put up some Teenage Mutant Ninja Turtle posters. Have toys, write something on your wall. Buy some ZenPencils posters. Have something that you want to look at; change it often.

As an illustration of this concept the below are some videos of professionals showing the rules of their spaces:

Casey Neistat: Red Boxes

Tom Sachs: Sacred Space

I’m writing a book about successfully working from home; click here if you want to know when it is complete.

Write in 2012

Last year I resolved to write more this year.  I ran across the idea of Morning Pages and found a writing site and some tools that helped me no matter where I was.  In this post I’ll talk about what this has meant and done for me and encourage you to spend some time writing in 2012 ’cause I think it is dope.

I write first thing in the morning and then intentionally at lunch a few days during the week or I jot down notes as the day passes over me.  I just write anything.  Sometimes it’s in the form of a 13 year old girl’s diary in that I dump my emotions on the page and other times its intentional work towards a blog post.  More often it’s simply noting patterns, entertaining myself, and processing whatever is in me.

Most of the writing that I do is not published – it is a language of communication in which the sender is the present me and the receiver is future me.  I started writing in 2002 after graduating college and being really bored in my first job.  I wrote it on a Movable Type blog that had a password on it – a personal pay-wall of sorts to ensures that only I read it.  Write for yourself first.

Why spend time writing?

If you don’t intend to ever pursue writing as a career or serious hobby why would you spend time writing?  I mean don’t you have Facebook stalking to do and fart apps to download?

Well let’s start with a list of small to medium-size benefits:

  1. If you work for a small business you can easily use your writing skills to establish a culture, public voice, and internal attitude for your company.
  2. It doesn’t matter what your job is – if you can clearly convey an idea over email, the phone, text message, smoke signal etc. you are going to be better at your job. It is a natural prejudice but a positive one: if you can clearly communicate people think you are much better at other things.  Software developers with clearly-written blogs are thought to be great programmers even if it isn’t so.
  3. Writing gets you in touch with yourself – what is in you comes out with stream of consciousness writing.  It reveals your prejudices, in-the-moment emotions, and things that you can’t process without “talking about it”.
  4. Archived writing is stored state of mind.  I go back and read stuff I wrote when we had our first child in 2007 and it is fascinating and beautiful just because it takes me back there better than music or photos.
  5. Writing is an effective break during work – you clear your head in the same way that reading does while keeping your mind more active.
  6. Writing gets new ideas out of your head and new ideas are stuck behind old ideas.

On to the bigger benefits:

Writing helps you learn to create

In writing you create something from nothing.  Most of us don’t think that we can draw or sing or dance or freestyle rap but any literate person can write.  You don’t have to be fancy; you can write a story about anything to please yourself and create a thing. Creating changes you in many positive ways and writing is the most accessible of those ways.  One of my takeaways this year was how often I came up with something new while writing.

Writing helps you learn to focus

Writing is a very intensive focus-based activity.  You can switch over to a web browser while writing but the structure of words and sentences means you probably won’t do so in the middle of typing out the word “encyclopedia”.  In this way writing is a good way to bootstrap your focus muscles – letter by letter, word by word, sentence by sentence, paragraph by paragraph, chapter by chapter, book by book, obscenity by obscenity.

Resolve to write

Anyway, my unsolicited advice: write something this year.  No excuses.

I’m writing a book about successfully working from home; click here if you want to know when it is complete.

Managing your Significant Other when working from home

I’m writing a book about successfully working from home; click here if you want to know when it is complete.

When you start working from home you have to prepare those around you for the inevitable consequences of this new lifestyle. I’d recommend telling your neighbors, kids, pets, imaginary friend(s), team of personal therapists, and parole officer.

And of course the absolute most important person to prepare is your Significant Other (SO). A lot of people who try working from home give up after about a month and when you ask them why they say “I was driving my wife crazy so she threw a burrito at my face”. If you do not properly handle the work from home transition (aka “The Great Move Away From Pants) you will eventually have a burrito thrown at you – I just proved it with science.

When you start working from home your SO’s life is going to change in unexpected ways and they need to be prepared for this shift. The way you communicate, interact, and smell are all going to change in ways that they don’t expect.

Why? Because of mismatched expectations about the benefits to their lives.  The sad reality is that working from home does not offer many benefits to the significant other.  Maybe eventually you will look at them more and will be able to do cool things like eat lunch with them sometimes or do them small favors. But the reality is that telecommuting (i.e. riding your phone to work) has certain realities that lead to other not so pleasant realities for your SO:

Change for you Consequence for your spouse
You can achieve higher productivity because you don’t have to deal with others slowing you down You are less patient
Less physical interaction with others Your SO now lives with a slightly crazy person who thinks that eating cereal with eggnog instead of milk is totally normal
Cooler coffee breaks, low key lifestyle They slowly begin to become jealous of the fact that you get to listen to music/watch Oprah while working
No longer have to shave or get all dressed up They now live with a person who thinks track suits are a good look
Full-time access to Internet and kitchen Live with 120% more juvenile and fatter version of you
You are always around You are 140% more annoying

You can see these realities and mismatched expectations when you announce your transition:

Honey, I’m going to start working from home.

Your SO hears other things:

Sweetheart, I am now available to wait for packages and repairmen for you full-time.
Organic maple syrup, we can now talk on the phone for four hours a day divided up into separate conversations spaced 17 minutes apart even when I’m in the bathroom.
French Toast sticks you can eat on the go, We are going to save $400 a month that we used to spend on gas and soap so feel free to spend that guilt-free by yourself on something that upgrades our lifestyle permanently without chatting with me first.
Peanut Butter M+M Gift Basket, I have achieved more freedom in my life and you should let your jealousy boil slowly like in a rice cooker until it burns our intimacy like if you picked up a rice cooker and it was crazy hot so you dropped it on your head and wow that hurt.
Never-ending pancakes from IHOP, you know how when you call me at work you say I’m sort of a jerk and are different and sound stressed – you now live with that version of me!

The SO Management Plan

You need to make sure that your SO knows what working from home actually is and establish the below ground rules.

You wouldn’t like me when I’m working from home but will like what it makes me.

Tell your spouse / girlfriend / live-in monkey what working from home is – a risky challenge with a high payoff.  Working from home is stressful – you have to work much harder at staying in the loop, reading between the lines, networking, and focusing to get things done.  Managing the tension of working out of your home – where you used to just relax – is not easy. Let them know that focused/work version of you isn’t chill/at home version of you.

You working from home may offer no direct benefit to your SO but does offer massive benefits to both of you.

Working from home successfully is not easy and might not be all roses and free burritos for your spouse, but it does offer them some good overall relational benefits:

  • When you work from home you are more in control of your environment and schedule thus leading to an overall happier version of you
  • They no longer have to listen to you complain about co-workers (because cats are not co-workers)
  • You can, if managed properly, save an amazing amount of money
  • You can, if managed properly, have free time in the middle of the day to do other things (if you have a typical commute you can gain 10 hours a week to spend with your family, level up in your favorite video game, work on your novel, tweak your karaoke robot – whatever.  For those of your doing the math at home with an abacus: 10 hours is more than a typical workday that you gain.)

Separating work from home is a critical component of telecommuting success and is the only one they can help you with

Your SO can’t help you communicate effectively, stay organized, stay professional, and get more things done but they can help you separate working from non-working.  There are two common complaints that affect worker and SO: the SO complains that the worker continues working past normal work hours (since the office is right there) and the worker complains of being constantly interrupted by their SO during the day.  Both of these common failures are just cases of work and home not being separated aggressively.

How to separate work from home is a separate topic, but the attitude should be that during established work hours you simply aren’t there.  Any interruption should be run through the filter of “Would you have called me during work for this?”.  I have my SO text me just like she would have if I had been at work – don’t knock on the door.

I’d also suggest a month trial run in which you have very hard and fast rules about work hours, communication, and availability so that you set expectations firmly – i.e. as the worker don’t be helpful in the beginning.  The space this creates allows them to realize that after they leave you alone for a while you are able to establish yourself as a reliable telecommuter that you will be a more relaxed version of yourself.

Being left alone and in charge leads to super-productivity if you are intentional about it, and having more control means more freedom means more happiness, and will allow the sort of things that they desire.  When the Cheetos-dust clears most SOs when given the choice prefer a happy slightly crazy/stinky spouse to a clean miserable one.

I’m writing a book about successfully working from home; click here if you want to know when it is complete.

How to convince your employer to let you telecommute (LIKE A BOSS)

I’m writing a book about successfully working from home; click here if you want to know when it is complete.

You have decided to work from home. Telecommute.  Listen to the kind of music you want to – dance the way your body tells you. Shower less, love more.

La-di-freaking-da – you still need to convince your traditional in-office boss to let you do it.

What your boss fears

Your boss thinks that working from home is all Saturday-morning: pajamas, fruit loops, SpongeBob SquarePants, drinking, gambling, loose women, not working, cursing off the Boss (“BWAAAHH this bar gets Wi-fi look at me on IM right now guys!”). (ed note: Saturday mornings are pretty exciting for me)

He has heard horror stories of people working from home just doing enough to get by, not returning phone calls, working on other things, quitting, etc. He fears that:

  • Your performance will decrease
  • You will lose touch and work on the wrong things
  • You won’t be there to help others

Therefore he is afraid he will:

  • Look really stupid to everyone else for letting your try it
  • Have to let you go and find someone else

We just need to fix these concerns one-by-one in a detailed manner. You need to think through and deliver a proposal  – and then you need to be a badass and execute it.  He is most concerned with Performance and Communication.

Performance: prove that it will increase

You need to show that for you working offsite is more productive. Tell him why and then show him its true.

Send him studies and a summary of their conclusions to show that it can work

Studies say that:

  • People who work from home don’t change jobs as often
  • People who work from home have better morale (which leads to nice things like staying alive, being less stressed, and having more ideas)
  • People who work from home end up doing more actual work / work longer hours (emphasize whichever one your boss seems to care about more)

Finding evidence is easy:

Show him how much it works for you

  • Ask if you can hole up in a conference room for the afternoon, and then show him scary results.
  • Ask if you can work from the coffee shop/hotel across the street, and then show him scary monster results.
  • Ask if you can work from home one day and then show him scary monster-who-is-taller-than-average results.


There are two fears about communication – one specific fear is that you won’t be productive simply because you will be out of the loop and the other is that you will be a roadblock that holds up others.

Over-Communicating Status

For status the simplest method is to email what you are planning to do at the beginning of the day, and email at the end of the day with what you did. This also acts as a clock-in/clock-out mechanism for the more paranoid set.  Over-communicating is a good place to start – you probably aren’t offering twice-daily status updates in person now.

Offer to share your to-do list. When you work from home you will need more structure than you had before so you will most likely be documenting more anyway. Use one of the many tools (RTM, Workflowy, Toodledo) that offer sharing so that your boss can (but most likely won’t often) see that you are in fact adding and deleting items that he recognizes.

Be available

For team communication it is harder to stay in the loop.  You need some infrastructure in place: broadband internet, slower internet or a close Wi-fi backup, Skype, clear phone, etc. You will need to have your cellphone with you all the time when starting out and will need to act like you are in the office: if you need to run a 30 minute errand or have a doctor’s appointment tell someone.

Smell the tasty politics

For on-the-fly information and politics it gets much harder.  Since clearing communication roadblocks across the team might (absolutely should) be part of your boss’s job you are indirectly asking him to do more work by communicating differently with you so avoid any special cases that require him to do anything just for you.

Take the initiative on your own to identify how real information travels around the office and make sure you can show him what proactive steps you will take. e.g. “I’ll still be on the morning call and I’ll message Cathy around lunch to see if anything comes out of the Thursday interdepartmental fist fight that seems to always determine our priorities”.

Being in-office also helps – offer to do 3 work from home days and 2 non work from home days. If the days are typically the same (i.e. there is no big planning meeting) offer to still come in on Mondays and Fridays. This calms his SpongeBob nerves as an irrational fear of ninja three day weekends is common.  On the days you do come into the office you should turn into a total water-cooler guy and try to catch up with people to see if there is anything you need to know.

The most badass move out there

So you give him your plan – I’ll work Tuesday – Thursday from home from 7AM to 4PM, be available over IM, on Skype as needed, dial into the stand-up meeting, share my todo list, keep in touch with Cathy about politics, call you once a week if I haven’t seen you, etc.

Setup a timeframe of one month in which you will execute this plan. Tell him that at the end of it if he feels that you got less done you’ll give him the vacation days you would have earned over the period back.  If you are a contractor offer to not be paid for 2 of the 20 business day in play, or 10% of your billed time over the period.  Also – you should fully intend and be ready to make good on this.

The reason this works is that you are putting a stake in the ground and providing a mutually beneficial outcome for both parties.  The boss knows that he is still in charge but has an employee that is taking initiative and will get things done.  The added benefit to you is that it puts you in the right frame of mind – the absolute most important thing to understand about working from home is that it is all about execution.

(The second most important thing about working from home is never missing an episode of SpongeBob.)

I’m writing a book about successfully working from home; click here if you want to know when it is complete.

How to deal with robots and get your poodle a job

How should you act when a recruiter calls you during personal relaxation time (i.e. grooming your pet poodle “Fluffikissh”)? What are the ground rules for interacting with robots? If the end goal of everyone is to have a good reputation and to earn a living what are some long term things we can do to get there?

You can interact with a recruiter in a bunch of ways:

  • Unsolicited email
  • Phone call
  • Prank Phone call
  • Awkward stare
  • Love Letter
  • LinkedIn message
  • Scheduled Social Interaction (i.e. poodle playdate)

Tech recruiters get a bad rap because a good deal of the initial communication is unsolicited and untargeted. (er, spam) I’ve gotten many emails about positions that I am not qualified for in any imaginable way – they might as well for jobs as a mime.

Fact: mimes have a difficult time getting referrals from others mimes over the phone.

It’s pretty simple really: be pleasant, professional, helpful, and don’t be a jerk.

Be professional: Don’t waste their time

If you are a Ruby on Rails hacker living in New York and you get an email from a recruiter casting a wide net looking for talented programmers for a position on Yourass, IL to work on YourElbow v2.0 (NOT 3.0 or 1.1) – just delete the email. Do not write back the recruiter and waste their time. Don’t get upset and bad-mouth them to your friends – they are either clueless and junior in their industry or they are desperate to find somebody with a rare skillset. Shame on you for using your email that you check every 15 minutes anywhere having to do with a job ever.

Side note: I once got an email looking for a “Pearl Architect”. There are 3 bugs in that statement (perl: NOT EVEN ONCE)

Be Pleasant: Don’t Assume

I have met a lot of developers that can’t stand recruiters recently. The bad-mouthing that goes on in places like Hacker News is pretty brutal. A developer on Hackers News complaining about recruiters is very close to a college graduate complaining of a person whose entire job is to help you find a job you like. Every time you waste 30 seconds on a recruiter think “this is a good problem to have”.  When you meet a new recruiter don’t start out the relationship by telling them about the time that one recruiter lied to you and broke your heart.

Be Helpful: Think Long Term

Recruiters do provide value and a good recruiter (like a good mechanic or a person who has never tried Skittles) is rare. So think of every interaction with a recruiter as you vetting out two recruiters that at some point in your career you will use to either get a job that you really like (“I always wanted a job where Fluffikissh could be my personal assistant”) or to help out a friend who is either breaking into the industry, has moved from a new place, or is simply looking for something specific.

Don’t be a Jerk

Now is a good time to be a developer. Our entire industry, especially the value-creating role of a developer of products, is a buyer’s market. Don’t let it go to your head. You are not that special. Don’t be a jerk to a recruiter – in the same way dishonest recruiters are eventually spit out of the industry – no matter how good a hacker you are the word gets around that the freak with the poodle is hard to work with. Stay classy.

A system for analyzing systems [Part 2]

This is the second part of an (awesomely epic) series on how to analyze a software system quickly, click here to view Part 1.

So now you (having the right attitude and documenting everything) have viewed the main nouns (data) and verbs (use cases, workflows).  What do you do next? Profit?

#3 Find integration points and environmental concerns

It is important to understand the system within its software ecosystem – find the system edges:

  • Make a list of the technologies used (again – avoid judgment)
  • Make a list of the integration points (other systems, off the shelf products, web service apis, manual steps in overall process)
  • Look at dll references, build files, web references, configuration files, database connection strings, etc.
  • Draw a simple sketch of the application within its context with others

#4 Read some code

This is normally where developers start – reading semi-colons.  But maintain some discipline:

  • Make a simple outline of the project structure and main namespaces and entry points. Input, processing, output.
  • Try to not go down every rabbit hole too quickly – add to your WTH list liberally and then circle back.
  • Guided by what you know already dive in based on what makes sense – read the billing module, the calculation piece, the ranking algorithm, or the integration with Facebook.
  • Document system conventions, code conventions, and architecture. The build order can be useful and painfully revealing here – on larger projects I break out ndepend to see the overall structure.

#5 Read some documentation

If the project has some artifacts now is a good time to read them. Most people will read them earlier in the process but since documentation is a record of what was the truth during a time in which the truth was still being figured out when people had time to do such things I’ve grown untrusting of it until I know what is what in the application. Project documents are fascinating in that they provide historical clues to design decisions, project status, pressure, and onetime events like data conversions and client meetings that affect the system in the future. Read up and take notes. Be aware that some pieces of documentation are position papers and do not represent the current reality.

#6 Talk to some people

Armed with nouns, verbs, and a basic understanding of the code go get your questions answered by someone on the project (if they will return your calls). A few tips for this process if a developer is handing off to you:

Realize that when a developer hands off they will do two things:

  • Blow off steam (I really didn’t want to do this but that freakshow client forced us to)
  • Play defense / apologize (I was under pressure so just hacked this up)

Let this happen, avoid judgment and be friendly and helpful.

#8 Identify the Win Condition

By this stage in the game you should know the “win condition” of the system – when it works how it provides value to a customer.  Examples would be:

  • “Allows users to find out about flight delays before other airlines, saving them time and allowing them an advantage against other travelers in a cancellation scenario” (FlightCaster)
  • “Provide an easy to use way to update online ads across multiple platforms based on your inventory” (Tentail)
  • “Allows users to find out about current events much faster, trade cat pictures, and waste half of their life” (Twitter)

#8 Wrapping up

So now you have your document with just Facts and Questions having hopefully whittled down your WTH list. Polish up your facts and add a summary statement and the application “win condition” to the top and you are done:

EasyTrack is a web-based accounting system used by small businesses that is built on ASP.NET Web forms with a SQL Server 2005 database. It integrates with Quickbooks, exports transactions as csv, and has a web service api for 3rd party integration. It syncs nightly with a client customization of an older version that uses the same database but has a non-web frontend. It works in Internet Explorer. Its niche is being an easy to use tracking system for a discrete set of common accounting tasks that are harder to do with larger systems.

A system for analyzing systems [Part 1]

We seek definition to understand the system so that we can discern
the rules so that we know what to do next so that we win.

— Michael Lopp, Being Geek: The Software Developer’s Career Handbook

How do you approach learning a new system that is dumped on your lap like a spilled plate of nachos? Let’s say somebody walks up to you and says:

Hey nerd- we need you to look at the EasyTrack system tomorrow – we have a buglist that we need you to churn through before the end of the week. Ralph was working on it but after his nervous breakdown he won’t return our calls.

As developers we are asked to jump into complex software systems all the time and a big part of our value is simply understanding systems (not just changing them or making new ones). This is a skill that we need to be intentional about. We need a system for learning systems. Here is mine.

First steps: Attitude

Avoid judgement of the people who have worked on the system, the client’s goals, the choice of typeface on the one page of system documentation, the developer’s skills and experience, the organization of the code, the choice of technology, the choice of coffee used during the project, the organization of the altar built to the stored procedure that does everything, et al.

You have no idea the in-the-womb conditions on the project and don’t know the real trade-offs that were in play. Like many negative emotions judgement will close you down and cloud your thought so keep a clear mind when reviewing a system. Starting with a good attitude will also help you in talking to people on the project later on.

First steps: Document

As you work through the steps document what you are finding. When I do this my goals are:

  • To make me feel like I’m doing something as just staring at a new system can be brutal.
  • To make a deliverable that I can publish at the end of the system analysis if needed.
  • To allow me to have a place to store questions that I can’t find out from just reading code.

On that last point – I normally have Facts, Questions, and WTH sections in the document that I use as I work through a system. Facts are things that I have learned definitively about the system, Questions are open questions that I have researched and can’t find an answer to without asking someone or gaining access to something else, and WTH are bogeys – items that I see that I don’t understand that I’m deferring until later.

An example – as I’m reviewing the database I see an oddly-named stored procedure: spSyncOrderNoTransactionWithRollback? Hmm… So we add this to the WTH list until we can go back and read through it, where it is called, etc.  So we might end up with:


  • In spSyncChangeOrderNoTransactionWithRollback – how can you have a rollback without a transaction – is this nested?

Which leads later to the following:

  • Some of the stored procedures exist in the database but aren’t used by the application and are part of an export / sync process.  They start with spSync*
  • Some, but not all, of the stored procedures use nested transactions with checkpoint.


  • What is the export/sync process called by job execSync4_Bak that runs every night and calls the spSync* sprocs? [No access across linked server to the tables it is writing to]

As I work through the system I’m simply turning WTHs into Facts or Questions. The temptation once you have a basic understanding of the system is to stop typing – don’t do this.

If you maintain the facts list and polish it up you’ll have a nice system overview document. The easiest time to document a system is when it doesn’t feel like you are having to write-up up a bunch of things you already know.  So by writing while learning the system you can trick yourself into producing nice documentation that is much easier to keep updated later.

#1 Start with the data, don’t start anywhere else

I didn’t say start with the project plan, system documentation, email threads, interviews, test plans, or insulting notes about the system on the bathroom wall. The live data is the only thing that you can be sure is actually real in the beginning.

Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious.

— Fred Brooks, The Mythical Man-Month: Essays on Software Engineering

I’ve found this quote to be true – your code follows your data and you will get further faster if you understand the basic nouns in the application first. Seeing an Order table with a StatusId field gets you along the road faster than trying to read a 2,000 line method:

void placeOrder(int? productId, int priceStructureId, decimal price, int priceSigDigits, int userKey, string userNameInternational, bool isA, object? requiredBlob, out long intRetVal1, out long intRetVal3, out bool multi)

So go ahead:

  • Create database diagrams to identify relationships
  • Begin drinking if there are no enforced relationships
  • Look at table sizes to identify transactional vs. configuration tables
  • Look at meta and programmable database constructs – sprocs, functions, jobs, indexes, linked servers, etc.
  • Begin thinking through the possible workflows – an Order table with OrderDetail which points to Product and PriceStructure implies that in the application someone is purchasing something and that prices vary.

#2 Use the application

If at all possible get a login to the application to view it as a customer does. You can’t always do this safely but you should try. Developers are always saying that the UI is the tip of the iceberg and that all the logic is in the back-end, but knowing the data model and having poked around the application will teach you the vocabulary of the system very quickly.

  • What are the main uses cases [verbs] in the application?
  • What nouns/entities that we saw in the data model are actually shown to the user?
  • Is there data shown to the user that wasn’t in the data model? [hint for the next step]
  • What doesn’t appear to be working or isn’t intuitive? Enjoy this perspective as once you learn the rest of the system you’ll lose it forever.

Tune in for the exciting – no electrifying – conclusion to how to analyze a system for fun and profit.

The Three Laws of Robotics (for tech recruiters)

The tech market is so hot right now that if you are a developer and can tell the difference between O(n) and your own butthole you might be getting calls from aggressive recruiters. Recently I’ve had two recruiters that I’ve never met contact friends saying that I had recommended them for a position and I’ve heard stories of continued home phone calls, at-work phone calls, and all sorts of odd LinkedIn abuse.

I’ve heard many people say that recruiters don’t have much value, but I strongly disagree – we just need some agreed-upon moral boundaries. Let’s use Asimov’s Three Laws of Robotics [If you haven’t heard of these I’ll just hold on to your geek card while you go read that…]:

Law 1: A recruiter may not injure a human being or, through inaction, allow a human being to come to harm.

Harm means:

  • wasting my time
  • affecting my reputation
  • affecting my friend’s reputation

A recruiter shouldn’t hurt me, they should only help me and themselves in that order. Long-term it can work out for both of us; don’t affect my reputation negatively and I won’t affect yours either.  Some more specific ways they can harm me:

  • Submitting my resume to anybody without talking to me
  • Saying that you know me when you don’t
  • Talking to a 3rd party about me without us knowing each other
  • Being dishonest about the positions that you have in order to have a conversation with me

Law 2: A recruiter must obey the orders given to it by human beings, except where such orders would conflict with the First Law.

If I say I am not available at this time, don’t want you to do anything on my behalf, or would like you to stop calling me and crying into the phone – I mean all these things [But if I’m honest the crying does help me sleep].

Law 3: A recruiter must protect its own existence as long as such protection does not conflict with the First or Second Laws.

Of course there is a place in this world for recruiters and they should be allowed to make a living.  There is a lot of tech-recruiter-bashing but they are valuable for a hiring manager in that:

  • they can maintain a healthy pipeline of competent people [still up to you to find the people out of this pipeline]
  • they can filter people by personality [still up to you to detect people you don’t like]
  • they at times have a very good sense of the competency of tech managers (as they see loyalty from movement)
  • they can tell you who *won’t* work [they will filter out some incompetent people and some jerks]

They are also valuable for people looking to get hired:

  • they can tell you a good deal about the internals of particular companies
  • they can provide serendipitous events like connecting you with people that you end up working with later
  • they can help you get back out there after staying with one company for an extended time by giving you a feel for the market

We can even apply the later-added-4th law to recruiters:

Law 4: A recruiter must establish its identity as a recruiter in all cases.

Recruiters go to user meetings, tech conferences, social meetups, etc. I’m not sure if recruiters have gang signs (throw up a P for placement) but you should identify yourself as a recruiter to everyone other than the tollbooth operator that you talk to while you are working.

Following these laws will go far in re-establishing the reputation of recruiters within the technology industry.  Also: free pie mailed to my house.  Contact me for more details.