A week ago I was brought on to do support on a project I had wrapped up earlier this year. The client is bringing the project in-house and asked for help getting their team up to speed. It's interesting hearing feedback from developers other than my coworkers.

A couple big things stood out to me based on the first few meetings.

Build processes should not be magic

Automation is tricky because it can be incredibly powerful when used clearly for repetitive tasks and extraordinarily irritating when you can’t figure the “magic” out. The tasks that confused my most recent client were ones that were labeled vaguely or completely undocumented. A clear summary of all Grunt tasks was missing, which forced the developers to look into the Gruntfile itself, for example.

Show HOW in addition to WHY

One of the first steps in learning to code is documenting tricky sections, usually done through inline comments or blocks. This is helpful when troubleshooting a particular section, but often we leave out class or file-level overviews or how to even get started.

Heavily document getting started materials

Have you ever had to make updates to an old project and realize you’ve forgotten how it’s set up? Imagine how confusing it is for someone who’s never seen the project. Some useful things to have would be:

• Development environment setup
• How to start and stop servers or build scripts
• High level overview of architecture and relationships between components
• How to add new custom modules
• How to add new vendor materials and plugins
• Progressive enhancement strategy and support constraints
• Back end and template integration steps
• Who has worked on the project previously

Most of these things are part of the spiel you get when starting a project. Writing them down could save you time ramping up another developer (or yourself) down the line.

Favor simplicity

Simple things are easier to understand than complicated things. Next...

What about the README?

To be honest, It’s never been my first instinct to look at a README file first. I’m always looking to online documentation or Stack Overflow when the solution is right under my nose. I’d like to change that. I think one way to help would be by prioritizing the README from day one. If anyone remembers this article from back in the day, Tom Preston-Werner describes additional benefits of this approach.

P.S. Shout out to Paul and Chris for writing a kick-ass README on their last project and making me think.

The Next Project

I’m hoping getting this initial feedback after a project handoff will help me create more readable and maintainable projects. I plan to do a follow-up post after this support engagement is complete with additional uncovered issues and steps I’ve taken to make sure my projects are successful after a handoff.

Update (December 30th, 2015)

Unfortunately (for the post), the client didn’t have much feedback for us past the initial information gathering stage. The takeaway for this one being that upfront documentation and planning can make a very successful handoff!