readme

Written on 12 May, 2014

Since last year’s switch to freelancing, there’s been a large increase in projects that require me to jump into an existing codebase. Clean slate projects no longer take up the majority of my workload.

When working with startups, this often means getting my head around a reasonably sized Rails app. Because almost any developer would recognise at least some level of complexity inside a Rails app codebase, I’ve always been provided with some documentation via the repository’s readme file.

It’s actually the smaller scale websites that tend to provide the easily avoidable headaches. With less code and fewer tools being used, developers seem less inclined to document the environment.

But with modern web development, it’s rare to find a website that doesn’t utilise at least some sort of tool or service provider. CSS preprocessors, web font services, build systems, gems and dependencies, front-end frameworks, content management systems — at least a handful of these will generally find their way inside a project.

Because tools seem to get smarter each day, these examples I’ve mentioned are normally super simple to get up and running, if you’ve worked from a blank slate.

Things get a whole lot harder when you’re thrown into an existing environment that utilises these sort of tools, even if the codebase is a small one. It’s not easy to work out if the original developer used CodeKit to compile their CSS, or guess who holds the TypeKit login details. Nor is it easy to work out the dependencies of Gulp.js or figure out the structure of multiple asset folders.

Things that may seem obvious when you’ve worked on the project from the start, could cause some real confusion with project newcomers.

Here’s an example of a basic readme I recently put together for a small Jekyll website. This 5 minutes of work could save hours for a future developer.

In the past we could get away without documentation being a requirement for smaller websites. With static HTML, CSS and JS being the standard, the development environments barely ever caused confusion. But with the recent surge in tooling, a well written readme file needs to be a priority, even if you don’t ever envisage handing the project over to another developer or team.

Want updates?

Get an email each time I write about design and tech. Zero spam. Or, follow me on Twitter.