The Dreaded Documentation

by Erik Reagan

Last year I gave a talk at the EngineSummit 2 on documenting EE projects. I’ve learned a lot the hard way in the past and I want to share the ideas and approaches with you. Hopefully you can avoid the mistakes I made.

While it’s important to supply your clients or content editors with some form of documentation—that’s not the form of documentation we’re talking about right now. We’re talking about documentation for you, the developer. Documentation for other developers who aren’t inside your head 24/7. It’s important (and I’m not the only one that thinks so) and we’ll talk about why.

In the EE community, and the development world in general for that matter, there are numerous scenarios in which one might work. You have freelancers who work for their own clients, freelancers who work with agencies, in-house teams of people, in-house solo developers and agencies who work for clients regularly. In each of these scenarios you will (hopefully) work on multiple projects over time.

Whether you’re the only developer on a project or a part of a larger team, it is important to not be the only person with knowledge of how things work. The best way to make sure that doesn’t happen is to create developer documentation as you work on a site. This documentation should help you easily pick a project back up after a year or more of not touching it. Also, it should help another developer easily begin working on the project and understand how and why things work the way they do.

Why Document a Project?

Simply put, it’s the responsible thing to do.

We are all providing a service whether it is for a client or an organization employing us. Our practices should serve their best interest and documenting our work would certainly do that.

Consider this. You built a website in EE 12 months ago and haven’t really needed to add any features to it since launch. Your client has been maintaining content just fine and the gears are running smoothly. It’s 12 months later and the client is requesting new features. Going back to that project, you’ll find that one or more of the following things have happened:

• There has been an update to EE with possibly bug fixes and new features
• There have been updates to some of the 3rd party add-ons used
• Some of the updates require a specific PHP version
• You have become a better EE developer and have changed some of your practices and approaches
• You have a new team member who you’d like to perform the updates

With each of these scenarios as a possibility, you have a number of factors that could slow down the process of adding new features to the site. You might need to do some code diving to see how things are working or see if any of your templates might “break” with updates. You might need to walk through everything with the new team member so they understand what’s going on before adding the new features. You might need to figure out what version(s) of PHP is in play on your server(s). All of these things could be simplified with existing documentation in place.

How Do I Document?

The key is to keep it simple, yet effective. Don’t make many assumptions on who will be using the documentation. I recommend keeping a flat file in either plain-text, markdown or textile format at the root of your project. It’s important to name it something obvious so that anyone coming in to the project blind can spot it. We use dev-docs.textile for ours.

It’s best to keep your documentation up-to-date as your progress in your code. You won’t want the overwhelming feeling of tackling it all at once at the end of a project. You’ll likely forget things that way also. So, start your documentation at the beginning of a project and keep adding to it as you go.

What Do I Document?

We don’t want to write down every little detail of a project. So what exactly do we write down? We log anything that may change from one site to another. In ExpressionEngine, that means we have our work cut out for us. Here are some basic details that could change from one project to another:

• Server Environments
• Channels & Related Groups
• Member Groups
• Templates & Groups
• 3rd Party Add-ons

Server Environments

I understand that not everyone reading this article is working in multiple environments. If you only work on the production (“live”) site then at least consider adding information on that environment to the documentation.

Each server environment can have its own set of versions. What’s key here is to keep a log of what versions you’re running of PHP, Apache & MySQL. You may come across an update that has a required minimum version of PHP and having that in your documentation makes it easy to find. You should also note any necessary specifics about your hosting company and domain (if anything is particularly unique).

Channels & Related Groups

Many people will tell you that ExpressionEngine’s greatest strength—you can do the same thing in a vast number of ways—can also be a source of weakness. That’s one reason you should document how you structure your site. For example, how a Channel relates to the menu structure of your site’s front-end. Here are a few questions to ask yourself when considering what to add to your document:

• Are the primary navigation elements all within a single Channel?
• Are they among numerous Channels? (Perhaps they aren’t even related to the Channels.)
• Do your Channels use Categories?
• Are any of these categories shared?
• How are Status Groups used in my Channels? (Any non-standard uses?)

It’s also a good idea to at least mention the use of custom field types here. This is especially true if you have to write any custom fieldtypes for the project. Lastly, I’d recommend a quick rundown of the page types used for each Channel. Keep it simple and use something like this:

The Blog has the following pages on the site:

• Blog landing page (/blog)
• Archive page (/blog/archive)
• Authors Page (/blog/authors)
• Categories list (/blog/categories)
• Single Entries (/blog/blog-title-here)

Member Groups

This one is quite straightforward for most of the site that we build. On more community-centric projects this can get detailed. With Member Groups it’s important to lay out who has access to the key pieces of your site. As you know, ExpressionEngine lets you fine-tune Member Group permissions. You don’t need to document every permission available so just consider some of the important items at hand. I tend to keep it down to the following items:

• Who has access to my Control Panel?
• Who can use any front-facing SAEFs?
• Who can manage other members?
• Which modules a Member Group has access to.
• What member-based spam prevention is in place.

Templates & Groups

When it comes to Templates I like to document in two places: our master documentation file and directly within our templates; this is important because they serve two different purposes. The master documentation file (where we’ve been working thus far) is for the high-level overview of the project at hand. The in-line comments are for “the now” of a project. If I open a template for editing now, I want to know the purpose of the template and how it does certain things.

Master Documentation

As with the other documentation areas, keep this short and sweet. I typically include the following:

• Brief overview of templates groups
• Use of Snippets
• Use of Global Variables
• Any access restriction in play?

Beyond that I occasionally put in some comments about Global Variables set inside EE’s index.php file. This may vary from project to project though.

In-line Commenting

If you only take away one tip from this verbose article, make it this one. Leaving comments in your EE templates is a must regardless of your level of experience. ExpressionEngine makes it easy by supplying us with “EE comment syntax.” They differ from HTML comments in that they do not get parsed in the HTML for the world to see. This gives us a lot of flexibility when creating our templates. Even further, with an EE-friendly IDE your comments can stand out from your code and aid you during development. I use an ExpressionEngine bundle for TextMate that makes this a breeze.

I try not to make any assumptions about the template or the person working in it. This is my small set of rules when creating every template:

1. Document even the tiniest template
2. Don’t assume you’ll remember how it works
3. Don’t assume someone else will understand it

Every template starts with a small header giving some context. That often looks like this:

This helps give context to what is occurring within the template. If my template utilizes embed variables I often document that as well. This approach can save a lot of guess work during the course of a later project development.

In-line commenting is only what you make it. I encourage you to be creative in your approach and just following the three small rules listed earlier. Your fellow developers (and possibly your future self) will thank you!

3rd Party Add-ons

The concept behind documenting add-ons is to have a log of which add-ons fulfill your project’s core functionality. While you may not need to document that you’re using a small Gravatar plugin in your blog, you would definitely want to document that you’re using Matrix to help build galleries. “Why?” you may ask. Well it’s simple. When I dive into a template to fix a bug or tweak a feature, how will I know the difference between a native EE tag and a 3rd party fieldtype? The answer is that I often won’t. So it’s important to document which add-ons supply some of the core functions in your site/project. (Note that this may come in the form of your Master Documentation file and/or in the form of in-line template commenting.)

If your clients lean on some 3rd Party add-ons for Control Panel functionality it’s also good to make note of those. For example, if you use Structure or Nav-ee your client may use that often when working with content or navigation. A quick note in the documentation would be beneficial for that reason.

Other Considerations

Believe it or not there are a few more things you might want to consider putting in your documentation. Since you’ve made it this far I’ll reward you with a simple list of suggestions:

• Multi-site manager use
• Custom add-ons
• Additional PHP libraries for CI/EE
• Any tie-ins to external sites or services
• Any core hacks

Final Thoughts

This is a lot to consume. The idea of “developer documentation” may seem daunting at first. Like many other “new” things it gets easier over time and eventually can become second nature. In the end you will be thanked by your teammates or maybe even your client. Let me sum it up with a recent example from our firm.

We had a new client who had an emergency on their hands. Their site needed an immediate upgrade from an old EE 1.6.0 to the newer 1.7. The previous developers had to hack the core to fulfill some of the project requirements. Thankfully they kept a simple text file document of their tweaks. With no hassle at all we were able to re-apply those hacks to the 1.7 version of EE and seamlessly upgrade the client in no time. Without that documentation in place the upgrade would have been near impossible without losing some of that hacked functionality.

Documentation saves time. And so should you.