After years of learning new things in fields like business, law, and software I have learned that the biggest variable in understanding something is the quality of writing and communication. Communicating well is hard and in technical fields not enough value is placed on good writing. Communities like Ruby are lucky to have folks like Michael Hartl and Sandi Metz that are gifted with the written word. All things being equal I will typically choose a tool or programming language that is better documented than one that is new and shiny.

When I was faced with some legacy code bases at MAPC that felt bad I struggled to articulate what was bad about them. It took more than a few hours of Googling to discover Martin Fowler’s concept of code smells. These code smells provided a menu of issues that might exist in a code base along with recipes for refactoring away these issues. If you do not have the right vocabulary you will struggle to communicate. If your audience consists of experts you can assume a shared vocabulary and knowledge base, but if your audience is not then you need to start from the basic concepts before explaining the more complex things.

If you are a beginning software developer the best two things you can do are to find good writing about software, and to try and teach what you have learned to others. By getting experience in communicating new concepts to other software developers you can see where your ideas and metaphors fail. You can also better articulate the reasons for why you do things in your programming language. Communicating what you are doing well not only helps you write better code, it helps you identify good writing yourself which makes learning new things easier.