Consistency is the key to successful engineering teams.
Here at NEWMEDIA we are constantly seeking ways of providing tools to allow our engineers to be more efficient. The consistency is critical when understanding and managing the technical debt created by a team of intelligent people. One area we spend a fair amount of time focusing on is the consistency of our infrastructure so that we can have the breathing room to innovate. We’ve heavily adopted Opscode Chef and Cookbooks to help bring our infrastructure to a consistent state.
Today I’d like to announce the release of a tool that we use to help our engineers develop cookbooks consistently. Drud is a Ruby Gem that allows us to generate README files for our cookbooks. It does this by focusing on proper use of a cookbook’s metadata. It utilizes the GitHub API to pull additional information associated with contributors. While the README may seem like a minute item to focus on, it does provide a surprising wealth of value that may not be immediately visible.
The first benefit is that by providing a well formatted README file others are capable of understanding what our cookbooks offer. If this is performed consistently it becomes easier for someone to evaluate a range of cookbooks at a higher velocity. It’s a terrible feeling to need a promising looking cookbook and then have to undertake a significant learning effort to use it. While one can spend the time reading through code, it becomes helpful to be able to make an initial assessment from a higher level.
By deriving the README from the cookbooks metadata we are able to help enforce proper use of attributes and dependency declarations. If an attribute or dependency is used in a cookbook, but it isn’t described in metadata it becomes difficult to discover. By using a tool that generates documentation from metadata we are providing an extra layer of quality control at the engineering level that reinforces a consistent methodology.
Well-written cookbooks will provide a good number of Rake tasks. These tasks can help with code style from tools like rubocop, domain specific style from tools like foodcritic, and test oriented tools like rspec and kitchenci. Drud evaluates the rake tasks for a given cookbook and includes them in the context of the generated README. This helps casual observers understand that a higher level of quality has gone into a cookbooks development and maintenance.
A final benefit of this tool is the integration it has with the Github API’s. We firmly believe that all structural components of infrastructure should be created in the public space. Each contributor to a project is valuable and should be recognized. Drud generated README files link back to each contributor’s profile with a count of the commits that engineer has brought into the main project.
Drud is a valuable tool that focuses on the “simple” task of generating a README file. The additional benefits of performing cookbook development “the right way” go far beyond a simple documentation file.