Documenting the past

My team is currently in the process of documenting a project we inherited. The project was a skunkworks effort and documentation wasn’t as important as proving that it works. The developer who wrote it is no longer on the project and isn’t the most pleasant person to interact worth so we are on our own. The interesting thing about this exercise is we are realizing how much lack of documentation cost a project.

The number one reason for documentation is so another developer can step in and keep the project running if you are hit by a bus, falling piano, or UFO. The big motivator for us is code refactoring and removing dead code becomes very hard without proper documentation.

I was watching a presentation by Jack Diederich on code reduction and one of the reasons he often hears against removing dead code is “It might be used…somewhere.”

As he points out when using a dynamic language it can be very hard to identify if code is called or not. He recommends adding a comment to indicate where code is called from. Using code coverage tools does help identify dead code but you need to have a full understanding of the use-cases or else you may accidentally remove code that addresses an edge case.

Documenting legacy components can be seen as an expensive part of a project but will ultimately reduce technical debt and save time later on.

Finding my color

When I first started developing web sites choosing a color was easy. There were not that many to choose from. Of course HTML at that time supported 16 million colors but any competent web developer would limit it to web safe colors. I remember working for a small startup and had to tell the head of marketing that the logo and branding colors were not web safe. The Visibone color guide came in very handy back then.

Today picking a color scheme for a web site is not as easy because you have significantly more colors to choose from. Now I should mention that not all colors appear the same on each monitor and people see shades of color differently. Radiolab did a great podcast on how we see and experience Colors.

[iframe width=”474″ height=”54″ frameborder=”0″ src=”http://www.radiolab.org/widgets/ondemand_player/#file=%2Faudio%2Fxspf%2F211119%2F;containerClass=radiolab”]

When I am developing sites for work it is easy because their are color guidelines I need to be in sync with. So here is my advice for picking colors for a personal site.

Start with one color

Most WordPress themes ask you to choose a plethora of colors (background, foreground, text color, title color, link color, etc…). You want to start with one color and select other colors that complement. The next question comes down to how to pick one color. Now people spend a lot of time and money to come up with a single color. There is a whole psychology behind picking colors.

Possibly one of the simplest way to pick a color is to start with an image that represents you.  I am an avid Scuba diver so I started with an underwater photo I took of a shipwreck. Oh the Places I've Been image

Now I am not a fan of background images. Frankly they can be extremely hard to do right and can add a good amount of size to a page. So I take the image and use a service like http://www.pictaculous.com/ to find out what colors I should consider.

Palette

Of the three colors selected I chose #001C4A.

Try out different schemes

I found my notes on color from Art class in College. There are plenty of different methods on choosing complementary colors which do not always translate well for websites. Even the tried and true 30/30/60 can look odd. Frankly you end up back where we started with color doesn’t always look the same and the color of the content (pictures, embedded players, etc…) can make that color look different.

What I like to do is just try different palettes that contain my color from popular color palettes sites like Kular, ColourLovers, ColoRatate, or Color Explorer. It is very simillar to the process of picking up swatches at Home Depot and attaching them to the wall to see if they work.

Lessons learned from project hand offs

Over the years I have started many project and handed them off to others both successfully and unsuccessfully. Now as developers we develop and document our code/project as though we are going to get hit by a bus, meteor, or falling piano the next day. Then we are shocked when another person looks at our code/documentation and can’t successfully pick up where you left off.  This weekend I performed a retrospective on my projects over the years and made a list of the following best practices.

Don’t expect the person owning your code to be like you.

I once had a developer tell me that his documentation is only meant to be a memory reference for him. This is obviously a bad practice however in many respects we document less for things we think is obvious. For instance I may write java code that will be handed off to another Java developer. Now I am a Test Driven Developer and utilize the JUnit library to verify all of my code. Now just because the developer accepting my code knows Java does not mean that he/she knows JUnit. So I may have each test case very well documented but that doesn’t mean the new developer knows how to run them.

I recently watched an interview with Alton Brown about writing a recipe. He recommended against documenting everything. He tried to document how to make a soufflé for aliens and gave up after 20 pages.  There needs to be context or shared experience for this to be feasible. He takes an interesting approach by applying cartography techniques to recipe writing.

Give the person a top 10 list

Just because the person will receiving responsibility for your project doesn’t mean they can absorb 8 months of knowledge in a week. Provide them a Top 10 list to keep the lights running for the project. It is also important to footnote this list with what is not included and would require deep knowledge. I once had a developer maintain a project with only that list only to have the project explode 5 months down the line. There needs to be an understanding that the list will not solve everything.

Give the person a fool proof work environment

Everyone’s development environment is different and a huge amount of time can be wasted trying to get your project working in their environment.

Get more than simple sign off

Most project management documentation emphasize the importance of obtaining sign-off from the other person before the hand off is complete. In my experience developers sign off on accepting projects like people accept iTunes EULAs. There needs to be more involved in accepting a sign off.

One technique I have done over the past few years is to give the new developer homework. If the developer can make an enhancement or fix a core defect then they know the code well enough. Performing a code review of their change doesn’t hurt either.

Go on vacation

There should be a sense of urgency to encourage the developer to take ownership. They do not need to be that self reliant if you are always reachable. I like to set a deadline where I will not be available. Now I should mention that you shouldn’t hand off a project and then go immediately on vacation.

Conclusion

Handing off a project to another person will force you to write better code and documentation. The best advice I can give is to have a backup person and hand-off code often. Some teams have adopted a process of handing off code every day (http://www.technologyreview.com/news/423451/making-smart-handoffs/).