Planning and documenting front-end components

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:

  • We need to build more reusable website components.
  • We need centralized front-end documentation from the start.
  • We need up-to-date access to a high level overview of the system as a whole.

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.

5 Comments

  1. Bud ParrBud Parr

    Garrett,

    You really nailed it. We’re in the same place, though it sounds like you’re farther along implementing.

    I think having to create the system so an external team can manage it is interesting, and we’ve been developing our system with that in mind as an exercise in clarity.

    The biggest problem we’ve had is that things shift as we refine our process and it’s hard to keep documentation up, but we’re intent on making this work.

    I recently read a book called “The Checklist Manifesto” (which is a better read than its title suggests) and it made me realize that we can tame a website development process that I thought was just messy by nature.

  2. Paul RandallPaul Randall

    I have implemented almost exactly the same thing at my workplace. I called it The Kitchen Sink, and included all of the styled elements in a single location for the developers to refer to it.

    So far, it has worked really well, but I like the way you have documented it in the screenshot.

  3. Adam BoothAdam Booth

    I feel this is a great idea and seems to have work well according to the other comments on this post. I agree with Paul Randall that the way you have documented this is extremely clear and concise. The elements shown are visually very nice and would enhance the design of any website and boost the credibility.

  4. Garrett WinderGarrett Winder's photo

    Thanks for the comments guys.

    Paul, I used to do the same thing – I just like the table a bit better because:

    1. It’s fluid so I can check that all components are location and dimension independent
    2. Just for the 'wow’ factor that it will hopefully create.

    Cheers

  5. SethSeth

    Fondant Fancy

Sorry, comments are closed for this article.