In my opinion, an API should be many things. Perhaps the most important thing it should be is easy to use. If it isn’t easy to use (because documentation is poor, naming in inconsistent, or because it’s just not well thought out or organized) than it will likely only lead to frustration. Not only will it be difficult to develop on a poorly thought-out API, but it will be incredibly difficult to maintain and extend an application built on this poor API. I’ve been thinking a lot about style guides recently, and the troubles clients often have when they can’t effectively use the site styles we (developers/designers) have put together for their project. With that in mind I wanted to talk about how your style-guide is your client’s API. You are the programmer/developer/frontendguy/whatever. You have put together an incredible application that allows the client to create and maintain pages (complete with enough Ajax to sink a ship). Now you hand the application over to the client, and they need to begin the process of populating content.
The Client Needs Your Guidance
In most cases the client needs your guidance. If you want a consistent look for headers, lists, paragraphs, etc, than at a minimum you need to train the client in the use of your styles. If you want to reduce the amount of support requests you get, you should probably even include a style-guide.
As a sidenote, we are strongly considering including a developer docs directory in each site we build that includes a styleguide, as well as other relevant documentation. Putting client documentation under version control, in a protected directory, accessible via a URL is in our near future I think/hope.
Unfortunately it seems that this part of a project is often overlooked.
Stay Responsible
Developers tend to focus heavily on functionality and usability. These are important topics that need attention. I would argue that if you are giving a client a tool, and the tool is beautiful, and the tool is easy to use, you still have work to do. Clients want to be able to manage content, and most of the time that content is managed through a WYSIWYG editor (for instance in TinyMCE or fckEditor). The client needs to know how to properly use the tool, and it’s your job to deliver a responsible interface. When I say "use the tool" I’m really referring to the implementation of your styles, and not the ability to, for example, make text bold. Here’s an example of what I consider irresponsible:
<div id="content"> <div class="contentMainHeader">My Header</div> <div class="contentBody">Content Here</div> </div>
This type of implementation is irresponsible in a lot of ways. As far as the client goes, this markup introduces unnecessary complexity. It has been my experience that little things like this cause clients to bail on your intended style. This is the point where you usually start finding font tags and other craziness in content added by the client (might I recommend htmlPurifier if you really want things clean). Here is an example of what I would consider responsible:
<div id="content"> <h2>My Header</h2> <p>Content Here</p> </div>
Forgetting about the fact that our content now has more semantic meaning, your client should have an easier time populating content. Most clients understand the concept of a header and have an easier time with its application. As for the paragraph, both TinyMCE and fckEditor are going to create a paragraph by default (unless line breaks are not converted to paragraphs). In my experience this simple responsible markup can save a lot of time in support requests. In my experience the simple decision to use html tags as they were intended to be used can have a big payoff.
In Conclusion
Use markup responsibly and you will reap the benefits in many places. Your clients will be happier. Search engines will be happier. Your developers will be happier because they don’t need to wade through messy html. Remember, html tags are your friends and they have a purpose. Before you decide to create a class for everything under the sun, think about that tag you should be using, and scrap the unnecessary classes.