Planning and documenting front-end components

☞ This article was originally written on 09-09-2011 at Erskine Labs.

At Erskine it’s more than just accepted, but it’s encouraged to question the way things are done. If something isn’t working, figure out another way and test it out with the team. We’re always experimenting and our processes are constantly questioned. The way we’re working now is ten times better than it was six months ago, and the same thing will happen in another six months. It’s inevitable.

We recently finished a project where the deliverables were a bunch of flexible components that together built up 20+ very distinct front-end templates. We had to make this in a way that we weren’t repeating ourselves, that was easy to manage and could easily be implemented by an external team. It was a daunting task.

When we got about halfway into the project it became clear that we needed a better way to document the components, naming conventions, and front-end implementation that made up the website. Another problem that comes up with projects like this is when you get further into the project, you’ve got to refine previously made components more and more to work in harmony together. Houston, we have a problem.

After putting way too much thought into all of this, I broke the issues down into a few simple rules:

Introducing the components table

The components table is a new way of developing websites that I’m currently experimenting with. You name, define and markup your components within the [fluid] table instead of inside the constraints of a website. Thus, answering all the rules above in one fell swoop.

We need to build more reusable website components

A website is a skeleton made up of an assortment of individual components that can work individually, side-by-side, and sometimes integrated together. Components should be plug-and-play, and they should be location and dimension independent. They don’t need to rely on an external source to be usable. Also, quality control should be built in at the component level. By breaking our websites down, and focusing on small elements at a time we can really dig into the details.

We need centralized front-end documentation from the start

When someone new jumps into a project, they need to be able to get up and running as quickly and efficiently as possible. They need an easy way to see how the pieces of the puzzle fit together. By it’s very nature, the components table is centralized documentation.

Sometimes we hand over front-end templates to an external web team for integration with their own systems. Developing with the components table means little to no extra documentation on project hand over.

We need up-to-date access to a high level overview of the system as a whole

We need a way to easily spot components that can be refined and integrated with each other. Flaws in the system need to be spotted sooner rather than later. Nothing is worse, or more !important, than an out of hand stylesheet. Also, when starting on a new phase of a project do we build feature X on top of existing code, or do we start fresh? What’s the naming convention for the shopping basket? This can all be found in the components table.

Though it’s just an experiment, the components table fixes a lot of the problems I’ve had with front-end development. Anyone else out there trying to solve these problems? I’d love to see what you’ve come up with.