A README for “Simple” Websites?

You know all those times that you, the developer, wondered “what in the world?” when you inherited a project? Or how about that rule about writing code for your future self, only your future self is an axe-wielding crazy person who knows where you live?

This aims to help that. But first, a definition.

The title of this post refers to “simple” websites. Any experienced developer knows that a “simple website” rarely is and, more importantly, “simple” is subjective. For the purposes of this article, a simple website means a more traditional website, most likely running on a CMS, that is created to either provide information or serve as marketing tool for a business. No major functionality that requires APIs, custom programming or plugins, etc.

Why a README?

A README file contains information about other files in a directory or archive of computer software. A form of documentation, it is usually a simple plain text file called READ.ME, README.TXT, README.md (for a text file using markdown markup), README.1ST – or simply README.

—Wikipedia

As someone who works on the web, I tend to see READMEs almost strictly for the various software building blocks used for building apps and websites. Content management systems, jQuery plugins, CMS plugins, etc. They’re pretty simple and aren’t (normally) the full documentation. But looking at how Wikipedia defines what a README is above, I believe that websites are a type of “computer software”. If that’s the case, then having a README for websites makes sense.

The bigger, over-arching reason a README is used is so that potential users can get a better understanding of what the project is about. In the case of websites, web developers will often create a user guide for clients. However, I don’t think I’ve ever seen a website I’ve taken over contain a README or anything close to one that's for the developer (whomever that may be months or years down the road). At least not contained within the production website files.

I’m one of those web developers that will absolutely take over a site for maintenance purposes. What that means is, after a company has had their site designed and built, they need regular maintenance. Sometimes the web developer or agency they hired in the first place won’t offer that type of service or the relationship changes and the company decides to move on to another vendor for maintenance and support. If and when I do take over a site for support and maintenance, there’s a lot of up front work that I need to do to become familiar with the website – the structure, the organization of the code, how the CMS was setup, etc. Without any sort of guideline for any of that, that up front work can take some time and it’s not work I can gloss over unless I want to feel greater pain later on. (This is partly why I often ask for permission to access the back-end of a CMS before this sort of working relationship starts.)

Now, I’m not under any delusion that anyone in the web development world owes me or anyone else anything once they’re done with a client project. The opposite is also true; I don’t owe anyone anything when the project is done (except to my client of course). But I aim to be as good a citizen in this realm as I can be, especially after seeing and hearing examples of the opposite. So I’ve concluded that providing a README for the websites I produce is a good way to continue with that and for two reasons:

1. It’ll help me down the road when I come back to a project months or even just a few weeks later.
2. It’ll (hopefully) help a future developer that I’ve either brought on to help me or that has taken over the project I was once in charge of.

My README template

“Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.”

—C2 Wiki page Code For The Maintainer

I argue that a README is a good step in avoiding that violent outcome, hilarious as it might be. So I recently took some time to put a template together for just that.