As a contractor, I am often thrown into huge code bases with just a list of instructions for environment setup and not much else.
The bummer is that for complex software systems, a list of setup instructions is of hardly any use without understanding the expected end product of the environment you are putting together.
I often wish I also had a list of things I was allowed to do as a new contractor / employee, but this is probably a discussion for another time.
When I buy a Lego set, I bought it based on what the final constructed product looked like on the front of the box.
As you are putting together the Lego set, don’t you sometimes find yourself referring to the cool picture on the front of the box as a general reference and motivator?
It is a huge help for people to be able to link specific parts of the final product to the stages of the construction. As a new person is trained, it helps to have a map on how the complex software system functions, it makes it much easier to envision the steps one would take to do initial setup and get started quickly.
It is hugely helpful for most engineers to get a product tour as the first thing. Then it is hugely helpful to get a rough diagram of how that product is constructed, especially if the development environment is complex.
In one case I was thrown onto a hugely complex multi-server web environment, into which my development server had to be integrated. In order to setup a development server there was a Wiki with step-by-step instructions. People were expected to follow the steps and all would be well. Unfortunately, the instructions were missing major steps. There was no general picture of the multi-server end product to act as an aid. It took me two days to get the environment up and running, then another week to really ‘grok’ why my dev environment worked so I could be productive. During that week, I had no clue how to debug my server side or client side code. I was largely just dead in the water for that week when it came to real tasks due to a lack of understanding for how the environment was structured. I even asked for help on some things, and my questions were largely incompatible with the language and culture on site. Well, it took about a week and a half, but I finally figured it all out (or most of it), and was starting to be productive on development tasks the second week.
About a month goes by, and we bring on some new team members. The management handed the team members the same instructions I got a month earlier and said: ‘Set it up.’
I took the initiative to intervene and help all the new team members out for their setup. It only took about an hour to show them the final diagram of what exactly they were constructing for their developer environment and how they were going to debug it.
As each new team member set up their environment, they were able to fill in missing parts of the instructions on their own because they had a final picture of what they were putting together for their specific developer machines.
My setup experience took about a week and a half to get really setup. The new people were up and running within a day with a full understanding of the development server they had put together and full knowledge of how to really develop within the environment.
I wouldn’t consider the new people ‘done’ with their setup until they had made a change and hit a breakpoint for front-end JavaScript code, as well as made a change and hit a breakpoint for back-end ASP.NET service code.
All the new people needed to be productive quickly was that final picture of the environment they were putting together, and it saved a week of time per developer.
In this particular case, I was not thanked by management. It was kind of a bummer. Management saw the extra time spent as unnecessary. They were so used to their environment setup after 5+ years that they couldn’t envision their setup as actually being semi-difficult or impenetrable to a n00b. When new people came on, they were reluctant to admit that they didn’t understand or that the instructions were lacking due to the off-hand way onboarding was handled.
From this, I learned the lessons of perspective and starting with the end in mind. I continue to try and apply this to every situation I jump into.
Many times we have new clients who are looking to migrate old code bases to newer code.
As we are going back and forth about steps and work for the migration, I try to keep the end in mind and show exactly what the final product will look like. During development, deviations occur from the initial plan or picture for the final product, but I always attempt to keep the picture of the final system updated.
By keeping that final system picture updated, it makes it easier to:
- Onboard new people
- Scope out changes
- Make understandable changes to the system
- Assess risk to other systems already in the system
- See if there are shortcuts you can take by using other parts of the system
In software, as in remodeling a Barbie Power Wheels car, results all start with that final picture in mind.
Super Development 
Leave a Comment