BlogmyQuery – BMQ

Creating WordPress tutorials is a fantastic way to help build the WordPress community and to increase your Web traffic. That’s no secret. Just Google “wordpress tutorial� and you’ll see hundreds of results. The complete novice will find scores of well-written tutorials clearly demonstrating the basics of the WordPress dashboard and of activating the default template, in simple jargon-free language.

Unfortunately, after the first few “Hello World!� tutorials, they are in for a bit of a learning curve. Suddenly, the guides start to skip a lot of details, assuming that the reader “already knows this stuff.� Others are simply written exclusively for advanced WordPress users.

So, where does a new developer go after square one?

In this article, we’ll explore how to create clear easy-to-navigate tutorials, and tailor them to the underserved “advanced beginner� Web developer. The entire goal of this article is to make sure we see many more tutorials written for budding new coders who are ready to jump to the next level.

Who Exactly Is An “Advanced Beginner�?

Advanced beginners are people who generally understand how WordPress works but don’t fully understand how to implement its concepts. They are stuck in that awkward stage where a “For Dummies� book has nothing new to offer but raw code is still vaguely confusing. In your tutorials, you should strive to eliminate this common “tough it out� phase.

For our purposes, let’s assume that we are writing for someone who has a reasonably good grasp on the following:

• Can read and write XHTML and CSS, but probably sits with a cheat sheet open to get through those tricky spots;
• Knows little to nothing about PHP;
• Can navigate the WordPress dashboard and has basic knowledge of image resizing and editing;
• Understands the basic idea and principles of WordPress, but not necessarily how to execute them;
• Appreciates the simplicity of WordPress templates but wants to learn how to create or tweak their own.

Admitting That WordPress Can Be Tough

We all need to stop pretending that WordPress is this magical dirt-simple Web development solution. Yes, using it is much easier than designing a custom CMS, but for new users looking to get under the hood, the tool can still be daunting and complicated.

For the average coder who is still just getting a grip on fundamental CSS, even the strange-looking batch of official WordPress folders that come in the installation ZIP file can be intimidating.

This is way more confusing for a beginner than seeing a simple HTML file, a CSS file and some images.

When you refer to a file such as style.css or an image, be sure to tell readers exactly where to look and where to save these files.

Basic Guide-Writing Principles

Before we delve into WordPress-specific tips, let’s go over some basic principles for any tutorial.

Keep It Tidy

Readers have sought your advice because they are confused. Don’t add to their troubles with a cluttered how-to article. Use plenty of bullet points, and keep paragraphs short. If you’re tackling a complex idea, split it up into sections.

Take the format of Smashing Magazine’s articles. Articles are broken up so that each sub-topic has its own section. This simplifies the navigation, makes the content more visually appealing and clearly guides the reader through the process.

Make Sure Readers Are Fully Prepared

Any good tutorial includes all of the resources it recommends. Don’t just say “make a blue imageâ€� — give it to them. Otherwise you risk over-complicating things for the reader. Provide sample files, and explain that your lesson will deal exclusively with these readily available resources. You wouldn’t want them to suddenly have to read a Photoshop tutorial when they’re only interested in learning how to customize their header.

This tutorial includes everything a reader needs to get started, including a visual demo and easily accessible sample files.

Define Your Goal

The best tutorials focus on a single topic. Plan the article before writing it. You shouldn’t explain every aspect of CSS and WordPress on every page of your website. What will readers get from this particular tutorial? A nice neat list at the top of the article should clearly define its parameters.

List the Prerequisite Skills

A tutorial should always list any skills that the reader will be expected to have. Instead of cluttering an otherwise focused guide with extraneous detail, provide links that direct readers to where they should go to learn about particular topics. This will help new developers who are nearly clueless, while keeping the article clearly focused for more advanced readers.

Tips Specifically For WordPress Guides

Now that we’ve discussed some fundamental organizational skills that will make any tutorial clear and easy to follow, let’s delve into some WordPress-related areas that many guides seem to miss.

Taming the Codex

The WordPress Codex is a powerful tool that can give your tutorial a much-needed jolt of clarification. Just be aware that to newbie designers, the Codex can seem like a massive labyrinth of articles, with each topic requiring that you read several earlier lessons in order to fully grasp. As the experienced coder, you need to show that, when used properly, the Codex presents the cleanest example of a concept.

The Codex is one of the most useful tools available to a WordPress developer.

Don’t just say “Check the Codex� and drop in a link. Your readers need context. Your main goal in writing a tutorial that refers to the Codex should be to eliminate the reader’s need to plunge into its depths. Tell them what they can expect to read on the page, illustrating exactly how they can use the particular lesson you’re linking to.

It might even be to your benefit to point readers to a “beginner’s guide� to understanding the codex. Here is my favorite.

Keep Them On Target, Visually

The most important thing to do to keep readers on track is to provide constant updates throughout the article on what they should be seeing in their own implementation. For example, if your tutorial is multiple pages, always start with an illustration of the finished product. After each milestone, provide a “Here’s what you should be seeing right now� example. Whenever possible, include working samples of the project or its parts for the reader to experiment with. (These functional samples might have to be run from the author’s server or a third-party website.)

A WordPress project could very easily require coding between a few files. If someone isn’t following closely enough, they could miss something simple that wildly alters their results. Your milestone examples will give readers up-to-the-minute feedback on where they are going wrong. It’s the best way to make sure you aren’t losing anyone.

Make Your Code Selectable

This is crucial to any WordPress tutorial. If you are explaining a concept in code, allow the reader to copy and paste the examples whenever possible. For curious readers, nothing is worse than wanting to test a sample line of code, only to realize that they have to fully type it out. This principle seems self-evident, but many guides simply explain an idea and say, “Add this code,� alongside a screenshot of the finished style sheet. If the reader misses one semicolon, all their work will be worthless. That’s infuriating.

While there may be some merit to having the reader actually write out the code, most people probably won’t see it that way. They are much more likely to seek out another tutorial, one that doesn’t force them to constantly rewrite code that they don’t yet understand.

Be Wary of PHP

While it’s a necessary part of WordPress, remember that to someone just getting their footing with something as relatively basic as CSS, PHP code can look like someone fell asleep at the keyboard. Too many tutorial providers assume that their readers understand even the first thing about PHP. This is often not the case.

In the likely event that you are explaining low-level PHP to readers, be mindful that they might be confused. Give a short description of exactly what is happening in the code. As always, provide a link to a relevant PHP tutorial.

Clarifying Custom Widgets

Admittedly, this recommendation is pretty specific, but bear with me. When I was getting started, one of the most infuriating things about WordPress tutorials was when they said, “Write a quick widget with this code…�

Now, once a reader has created their first widget, it becomes completely obvious that most of the time all they’ll need to do is drag the “Text Widget� and add some basic HTML code to it. But first they need to get past this initial step. Remember that to someone looking with fresh eyes, they may not understand your shorthand.

The blank text widget is a simple yet potentially deceptive name for a powerful tool.

So, I always like to see a description such as, “Use the ‘Text’ widget to create this option. You can simply add raw HTML into the blank box and drag it to your sidebars. This will then work just like any other widget.�

Always Provide Documentation for Video Tutorials

Without a doubt, video is a massive help for confused developers. It provides detail-rich, play-by-play instruction that carefully guides the viewer through the concepts in the tutorial. Just be sure to accompany the video with detailed textual documentation. Otherwise, people will repeatedly have to rewind and squint at the screen just to copy your instructions. That’s an easy way to lose fans.

Treat the video as an aid, not as the main event. This tutorial on Lifehacker, though not specifically for WordPress, illustrates this principle perfectly.

Update Your Tutorial As Needed

Keep your guides relevant and dynamic. Too often, tutorial writers will clarify major points in the comments section of their page, while the tutorial itself remains static. Or they just ignore the page entirely, leaving now-irrelevant guides to linger on the Internet.

Keeping in touch with your audience is wonderful, but giving new readers the best possible experience is also important. Don’t expect people to comb through two years’ worth of comments to find your changes.

Make sure your supplemental links remain relevant. Nothing is worse than reading a tutorial from 2007 and seeing the words “With a simple change, it should look like this!� Surely in 2007 that link was perfect, but if it leads to an unrelated page in 2011, it will undermine your entire article.

Tell Them Where to Code

Make sure that newbies are tweaking code in the right place. Point out that, in general, they shouldn’t edit files from within the WordPress dashboard. That leaves little room for error, and if the coder isn’t careful, they could lose hours of progress.

A brief glimpse at the SFTP- and FTP-enabled one-stop code editor, Coda.

Instead, teach them to use an SFTP- or FTP-enabled editor, such as Coda or Dreamweaver. It’s a safer, fixable way to correct any mistakes that arise.

Teach Them How to Test

This last point is just a personal preference that I wish more people would do. One of the best things about basic HTML and CSS is that you can easily test them locally by simply reloading the browser. When you jump into WordPress, this testing process becomes significantly more complicated. Advanced beginners will likely be lost once they realize that they can’t test by simply dragging their WordPress creations into a browser. This leads many new coders to test their unfinished creations on production websites.

Tutorial writers should stress the importance of not testing WordPress changes on a live website. Explain the myriad benefits of designing on a risk-free local server. Just point the reader to one of the many existing server guides, and briefly mention the pitfalls of testing code on a live website. Michael Doig’s article “Installing WordPress Locally Using MAMP� is one of the most useful set-up guides.

Conclusion

Whether you’re writing a tutorial about WordPress or anything else, clarity is paramount. Put yourself in the reader’s shoes. WordPress is built on the efforts of a wonderfully helpful community that is full of excellent tutorials and experts. But, as in any community, this has resulted in some confusing jargon and common shortcuts.

These can overwhelm new developers. Tutorial writers should avoid unnecessary jargon and always explain any references and functions that they use, no matter how basic they seem. Remember that, as the guide, your knowledge is likely far beyond that of your readers. What is obvious to you could be brand new to them.

By making your tutorials easier to understand, you’ll greatly increase your own Web traffic and enrich the greater WordPress community.

Other Resources

Here are a few tutorials that are easy to follow and that adhere to many of the points mentioned here.

• “Complete WordPress Theme Guide,â€� Web Designer Wall
  A great tutorial to help people get started in coding. Plus, it features an eloquent section on installing WordPress locally.
• “How to Make a Website: The Complete Beginner’s Guide,â€� Lifehacker
  An excellent blog across the board, Lifehacker has created some absolutely phenomenal video tutorials. The documentation makes this ones an expertly designed guide.
• “CSS Techniques: Using Sliding Doors with WordPress Navigation,â€� WP Hacks
  WP Hacks is a great resource for WordPress designers. This piece is well organized and demonstrates the correct way to present code in a tutorial.
• “Installing WordPress Locally Using MAMP,â€� Michael Doig
  This is the excellent guide to setting up WordPress using MAMP that I mentioned earlier.
• “How to Create a WordPress Theme from Scratch,â€� Nettuts+
  Nettuts+ is always a great source of tutorials. In this one, you’ll see how to present all relevant resources in a tutorial.

(al)

© Scott Meaney for Smashing Magazine, 2011.

Contrary to what you may read, peppering your form with nice buttons, color and typography and plenty of jQuery plugins will not make it usable. Indeed, in doing so, you would be addressing (in an unstructured way) only one third of what constitutes form usability.

In this article, we’ll provide practical guidelines that you can easily follow. These guidelines have been crafted from usability testing, field testing, website tracking, eye tracking, Web analytics and actual complaints made to customer support personnel by disgruntled users.

Why Web Form Usability Is Important

The ISO 9241 standard defines website usability as the “effectiveness, efficiency and satisfaction with which specified users achieve specified goals in particular environments.� When using a website, users have a particular goal. If designed well, the website will meet that goal and align it with the goals of the organization behind the website. Standing between the user’s goal and the organization’s goals is very often a form, because, despite the advances in human-computer interaction, forms remain the predominant form of interaction for users on the Web. In fact, forms are often considered to be the last and most important stage of the journey to the completion of goals.

Let’s clarify this last point by discussing the three main uses of forms. As Luke Wroblewski states in his book Web Form Design: Filling in the Blanks, every form exists for one of three main reasons: commerce, community or productivity. The following table translates each of these reasons into the user and business objectives that lie behind them:

Uses of forms, based on Luke Wroblewski’s Web Form Design: Filling in the Blanks.

Thus, the relationship between forms and usability have two aspects:

1. Forms can make a website usable or unusable, because they stand in the way of the user achieving their goal;
2. Forms need to be usable in order to help the user achieve that goal.

This post will focus on the second point, because a usable form will naturally contribute to the overall usability of the website, hence the first aspect.

The Six Components Of Web Forms

Web forms are a necessity and often a pain point for both designers and users. Over time, users have formed expectations of how a form should look and behave. They typically expect Web forms to have the following six components:

1. Labels These tell users what the corresponding input fields mean.
2. Input Fields Input fields enable users to provide feedback. They include text fields, password fields, check boxes, radio buttons, sliders and more.
3. Actions These are links or buttons that, when pressed by the user, perform an action, such as submitting the form.
4. Help This provides assistance on how to fill out the form.
5. Messages Messages give feedback to the user based on their input. They can be positive (such as indicating that the form was submitted successfully) or negative (“The user name you have selected is already taken�).
6. Validation These measures ensure that the data submitted by the user conforms to acceptable parameters.

Skype’s registration form contains all six components.

Tackling Usability Via Three Aspects Of Forms

Despite differences in layout, functionality and purpose, all forms have three main aspects, as noted by Caroline Jarrett and Gerry Gaffney in their book Forms That Work: Designing Web Forms for Usability:

1. Relationship Forms establish a relationship between the user and the organization.
2. Conversation They establish a dialogue between the user and the organization.
3. Appearance By the way they look, they establish a relationship and a conversation.

For a form to be usable, all three aspects need to be tackled. Let’s look at each aspect in turn to figure out how to make a form truly usable, along with practical guidelines that you can easily follow.

Aspect 1: The Relationship

“No man is an island,� the 17th-century English poet, satirist, lawyer and priest John Donne once said. Indeed, human beings thrive on relationships, be they amorous, friendly, professional or business. A form is a means to establish or enhance a relationship between the user and the organization. When done badly, it can pre-empt or terminate such a relationship.

With this in mind, a number of principles emerge:

• Relationships are based on trust, so establishing trust in your form is critical. This can be achieved through the logo, imagery, color, typography and wording. The user will feel at ease knowing that the form comes from a sincere organization.
• Every relationship has a goal, be it love and happiness in a romantic relationship or financial gain in a business relationship. Ask yourself, what is the goal of your form?
• Base the name of the form on its purpose. That name will inform users what the form is about and why they should fill it in.
• Just as in a relationship, getting to know the other person is essential. Get to know your users and always consider whether the questions you’re asking are appropriate and, if so, whether they are timely. This will instill a natural flow to your form.
• Knowing your users will also help you choose appropriate language and remove superfluous text. And it will help you craft an interface that balances your needs and the user’s.
• Do not ask questions beyond the scope of the form. In a relationship, you would become distrustful of someone who asked questions that were out of place. The same thing happens online. Consult with relevant stakeholders to see what information really is required.
• Sudden changes in behavior or appearance will make users edgy. Likewise, never introduce sudden changes between forms or between steps in a form.

Know your users. Make it easy for registered users to log in and for new users to register. Debenhams makes this distinction barely noticeable.

Amazon, on the other hand, simplifies the process for registered and new customers.

Aspect 2: The Conversation

A form is a conversation. And like a conversation, it represents two-way communication between two parties, in this case, the user and the organization. In fact, the user has filled out the form in order to initiate communication with the organization.

For instance, with a social network, a user would fill out a registration form to inform the organization that they would like to join. In inviting their request (whether automatically or manually), the organization would ask the user a number of questions (in the form of labels), such as their first name, last name, email address and so forth. Upon acceptance (or denial), the company would inform the user of the outcome, thus completing the communication process.

Viewing forms from this perspective yields some useful guidelines:

• As mentioned, a form is a conversation, not an interrogation. Aggressive wording in labels will make users feel edgy, and (if they do not leave) they will most likely give you the answers that you want to hear, rather than the truth.
• Order the labels logically, reflecting the natural flow of a conversation. For example, wouldn’t it be weird to ask someone their name only after having asked a number of other questions? More involved questions should come towards the end of the form.
• Group related information, such as personal details. The flow from one set of questions to the next will better resemble a conversation.

   

  Yahoo’s registration form effectively groups related content through purple headings and fine lines.

   

  

  While Constant Contact groups related content, it separates the groups too much, which could confuse the user.

• As in a real conversation, each label should address one topic at a time, helping the user to respond in the corresponding input field.
• The natural pauses in a conversation will indicate where to introduce white space, how to group labels and whether to break the form up over multiple pages.
• In any conversation, people get distracted by background noise. So, remove clutter such as banners and unnecessary navigation that might distract users from filling out the form.

   

  Dropbox provides a fine example of what a registration form should look like. The white space is effective, and the page uncluttered.

Aspect 3: The Appearance

The appearance or user interface (UI) is central to the usability of a Web form, and there are several guidelines for this. To simplify the discussion, let’s group them into the six components presented earlier.

1. Labels

• Individual words vs. sentences If the purpose of a label is simple to understand, such as to ask for a name or telephone number, then a word or two should suffice. But a phrase or sentence might be necessary to eliminate ambiguity.

  

  Amazon’s registration form contains full sentences, whereas individual words would have sufficed.

• Sentence case vs. title case Should it be “Name and Surnameâ€� or “Name and surnameâ€�? Sentence case is slightly easier — and thus faster — to follow grammatically than title case. One thing is for sure: never use all caps, or else the form would look unprofessional and be difficult to scan.

  

  See how difficult it is to quickly scan the labels in Barnes & Noble’s registration form?

• Colons at the end of labels UI guidelines for some desktop applications and operating systems such as Windows recommend adding colons at the end of form labels. Some designers of online forms adhere to this, primarily because old screen readers mostly rely on the colon symbol to indicate a label. Modern screen readers rely on mark-up (specifically, the label tag). Otherwise, the colon is a matter of preference and neither enhances nor detracts from the form’s usability, as long as the style is consistent.
• Alignment of labels: top vs. left vs. right Contrary to common advice, above the input field is not always the most usable location for a label. It’s ideal if you want users to fill in the form as fast as possible. But there are times when you’ll want to deliberately slow them down, so that they notice and read the labels attentively. Also, keeping a long form to a single column and making users scroll down the page is better than breaking it up into columns in an attempt to keep everything “above the fold.â€� Each style of alignment has its advantages and disadvantages:

  

  *Times retrieved from “Label Placement in Forms� by Matteo Penzo.

  

  Forms should never consist of more than one column. Notice how easy it is to ignore the column on the right here on Makeup Geek (not to mention the note about “Required fields� at the bottom).

2. Input Fields

• Type of input field Provide the appropriate type of input field based on what is being requested. Each type of input field has its own characteristics, which users are accustomed to. For instance, use radio buttons if only one option of several is permitted, and check boxes if multiple choices are allowed.
• Customizing input fields Do not invent new types of input fields. This was common in the early days of Flash websites, and it seems to be making a comeback; I have seen some odd input fields implemented with jQuery. Simple is often the most useful. Keep input fields as close to their unaltered HTML rendering as possible.

  

  Altering the interface of input fields will confuse users.

• Restricting the format of input fields If you need to restrict the format of data inputted by users, then at least do so in a way that won’t irritate users. For example, instead of displaying MM/DD/YYYY next to a text field for a date, consider using three drop-down fields or, better yet, a calendar control.
• Mandatory vs. optional fields Clearly distinguish which input fields cannot be left blank by the user. The convention is to use an asterisk (*). Any symbol will do, as long as a legend is visible to indicate what it means (even if it’s an asterisk).

3. Actions

• Primary vs. secondary actions Primary actions are links and buttons in a form that perform essential “finalâ€� functionality, such as “Saveâ€� and “Submit.â€� Secondary actions, such as “Backâ€� and “Cancel,â€� enable users to retract data that they have entered. If clicked by mistake, secondary actions typically have undesired consequences, so use only primary actions where possible. If you must include secondary actions, give them less visual weight than primary actions.

  

  Not clearly distinguishing between primary and secondary actions can easily lead to failure. The above action buttons are found at the end of a lengthy form for enrolling in St. Louis Community College. Just imagine pressing the “Reset Form� button by accident.

• Naming conventions Avoid generic words such as “Submitâ€� for actions, because they give the impression that the form itself is generic. Descriptive words and phrases, such as “Join LinkedIn,â€� are preferred.

  

  Although Coca-Cola correctly gives more importance to the primary action button, it settles for the generic word “Submit.� “Register with us� would have been more helpful.

4. Help

• Text to accompany forms Your should never have to explain to users how to fill out a form. If it does not look like a form or it’s too complicated to fill out, then redesigning it is your only option. Accompanying text should be used only where needed, such as to explain why credit card data is being requested or how a birth date will be used or to link to the “Terms and conditions.â€� Such text tends to be ignored, so make it succinct and easy to read. As a rule of thumb, do not exceed 100 words of explanation (combined).
• User-triggered and dynamic help Rather than include help text next to each input field, show it only where required. You could show an icon next to an input field that the user can click on when they need help for that field. Even better, show help dynamically when the user clicks into an input field to enter data. Such implementation is becoming more common and is relatively easy to implement with JavaScript libraries such as jQuery.

  

  Skype’s registration form contains both user-triggered help (the blue box that is triggered by clicking the question mark) and dynamic help (the suggested user names).

5. Messages

• Error message This notifies the user that an error has occurred, and it usually prevents them from proceeding further in the form. Emphasize error messages through color (typically red), familiar iconography (such as a warning sign), prominence (typically at the top of the form or beside where the error occurred), large font, or a combination of these.
• Success message Use this to notify users that they have reached a meaningful milestone in the form. If the form is lengthy, a success message encourages the user to continue filling it out. Like error messages, success messages should be prominent. But they should not hinder the user from continuing.

6. Validation

• Only where needed Excessive validation is as bad as its complete absence, because it will frustrate users. Restrict validation to confirming key points (such as the availability of a user name), ensuring realistic answers (such as not allowing ages above 130) and suggesting responses where the range of possible data is finite but too long to include in a drop-down menu (such as a country-code prefix).
• Smart defaults Use smart defaults to make the user’s completion of the form faster and more accurate. For example, pre-select the user’s country based on their IP address. But use these with caution, because users tend to leave pre-selected fields as they are.

  

  Twitter’s registration form uses both dynamic validation (for the name, email address, password and user name) and smart defaults (“Keep me logged in�).

Conclusion The Beginning

The word “conclusion� is not right here. Let this be your starting point to take what I have written about and apply it to your own forms. The good news is that there is much more to say about all this; you can find an abundance of resources on each point made here. For starters, three books are listed below that inspired me when writing this post. As I stated at the beginning, taking shortcuts by only tweaking the UI will not make your forms more usable. What more can I say? The theory is now with you. Go get your hands dirty.

Further Reading

• Forms That Work: Designing Web Forms for Usability, Caroline Jarrett and Gerry Gaffney
• Eyetracking Web Usability, Jakob Nielsen and Kara Pernice
• Web Form Design, Filling in the Blanks, Luke Wroblewski

(al)

© Justin Mifsud for Smashing Magazine, 2011.

Designers hold CSS close to their hearts. It’s just code, but it is also what makes our carefully crafted designs come to life. Thoughtful CSS is CSS that respects our designs, that is handcrafted with precision. The common conception among Web designers is that a good style sheet is created by hand, each curly bracket meticulously placed, each vendor prefix typed in manually.

But how does this tradition fit in a world where the websites and applications that we want to create are becoming increasingly complex?

Looking Back

If we look back in history, deep into the Industrial Revolution, we will see a parallel with what will happen with our handcrafted style sheets once the complexity of the products that we want to build becomes too great.

The Industrial Revolution (which took place approximately between the middles of the 18th and 19th centuries, starting in the UK) was a period of upheaval in society; several aspects of life were changing. Much of this was due to the way people produced goods: during this period, manual labor started to become mechanized. The textile industry, for example, moved from primarily human- to machine-based production, and its artisans started looking at ways to be more efficient.

One of the many products of the Industrial Revolution. (Image: McCord Museum)

These machines that were created with efficiency in mind were initially quite primitive, and the public didn’t know what to think of them. It took us some time to adapt the way we worked with them and the way we thought of them.

Jobs that previously required human labor now didn’t require anyone; a machine could do the job cheaper and faster; employees became redundant. But the jobs in which people were being replaced by machines were mainly repetitive ones, jobs for which manual labor didn’t necessarily make for better products — at least not in any significant way.

Some argued that the output suffered in quality, that machine-made objects lacked personality, that craftsmanship was being lost, and yet production improved and evolved. We were also getting to the point that some products were getting too complex to be made by hand anymore.

This revolution shaped the world we live in today and gave us access to things that were until then too expensive or even non-existent.

Getting back to our topic, we’re seeing increasing complexity in the world of Web design and CSS. We want to create increasingly complex websites and apps — systems so complicated that they cannot be made entirely by hand.

MobileMe, with its extensive functionality and comprehensive interface, is an example of a complex Web application.

The World Of Developers

Developers and programmers are already inclined towards automation. Developers instinctively avoid reinventing the wheel. They understand the need to automate production (at least some stages of it); they understand that hand-crafted code is not needed at every step of the process.

Even if you are a great front-end developer who knows JavaScript like the back of your hand, you still defer a lot of your work to jQuery or some other library. Even if you’re able to write the code yourself, the time you’d save by not doing that frees you to deal with more significant problems. The gains in writing a script from scratch are no match for the gains in being able to focus attention on problems that no machine or automated process can solve.

jQuery, a well-known developer’s tool.

The skills and knowledge you’ve gathered through the years are not in vain, though. This knowledge is what makes you the best person to decide whether to choose jQuery; it’s what makes you able to adjust a plugin that doesn’t quite do what you need; and it’s what makes you capable of determining the best tool for the job.

The Wrong Attitude

Web designers don’t approve of these kinds of shortcuts. This way of thinking doesn’t translate to CSS; in the world of CSS, taking these “shortcuts� is not well regarded.

We CSS authors have a list of dirty words that we avoid saying when we’re speaking with fellow Web designer friends. For example, when someone says they’ve used a CSS framework, the apology immediately follows: “It wasn’t our fault.�

Principles such as DRY (don’t repeat yourself) are not present in CSS.

DRY states that “Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.� This applies not only to code but to every aspect of a product, such as design itself. When DRY principles are followed, we’re supposed to end up with products that are of higher quality and easier to maintain.

We CSS authors don’t think of the cost of maintenance or the increased complexity that duplication and cancelling out of styles add to our CSS sheets.

We usually follow something closer to WET: we enjoy typing. Why someone would want to hand-code vendor prefixes for CSS gradients is beyond my understanding, but the truth is that some people do, and they take pride in it.

CSS authors — i.e. Web designers who write CSS — don’t like the machine. We don’t think any CSS that the machine can produce will ever be as good as the one we make ourselves by hand. But what if this is not true? What if the result is as good as our own manual labor from scratch?

Other groups have had the same fears. The Luddites were workers who fiercely opposed the Industrial Revolution and progress. They said that machines were taking their jobs — which was true. But they fought, protested, became violent and eventually lost. Things would evolve whether they liked it or not.

The Luddites, smashing the machine. (Image: Wikipedia)

Context Matters

It’s true that we don’t all code for the Facebooks and Yahoos of this world; your CSS’ performance might not be the most important thing to focus on in your projects. But this is why considering context matters, and this is why it’s important not to dismiss techniques and solutions because someone once told us they were wrong or dirty.

We can embrace the flexibility that some measure of automation gives us and focus our worries and energies on deeper problems. We could focus on so many things: accessibility, usability, design theory, psychology, business, economics, experimentation and even programming are all suitable candidates and are areas in which having some knowledge, even at a basic level, can greatly improve our work.

An interesting reading list. (Image: Mike Kuniavsky)

Expanding our skill set can give us a better understanding of the products we create, the people we create them for (and their context), and how they are supposed to work behind the curtains.

Rethinking our processes might lead to better quality work. It might lead to perfecting a machine still in its infancy. If we don’t deny mechanization from coming into our work, we get the chance to shape it so that it does exactly what we want it to do.

Try This At Home

If we look around, we’ll see that several people are already trying to change the way we write our CSS, whether by introducing some kind of automation or by looking at ways of creating style sheets that don’t bypass issues such as maintainability. We can take inspiration from the work they produce in a number of interesting ways. Below are some of the most prominent examples, but feel free to add your own list in the comments section.

Frameworks: Don’t Reinvent the Wheel

As mentioned, “frameworksâ€� are probably the dirtiest word in a CSS author’s vocabulary — or second dirtiest, after “Dreamweaver.â€� (Note: this article was written before the advent of Adobe’s Muse.)

Often when discussing the subject of this article, people walk away assuming that the message I am trying to get across is to use CSS frameworks. That’s not correct. But it isn’t entirely incorrect either. Let me explain.

Frameworks are an important tool in a CSS author’s repertoire. By that, I don’t mean that you should blindly use popular frameworks such as Blueprint or 960 Grid System. Sure, these frameworks have nailed some things, and we can certainly learn a lot from their flexibility and modularity, but it’s more important that you — especially if you’re on a team — adapt a framework to the needs of you, your company and your team.

Blueprint, a popular CSS framework.

Perhaps you or your company works with such disparate clients and projects that a framework wouldn’t really be helpful, though. Perhaps a library in which you can collect snippets of frequently used code would be more useful. Or perhaps a starter template is what you need.

Whatever you need, more often than not you can find a way without having to reinvent the wheel from project to project. And if indeed you work with a number of other designers and developers and share CSS, then these tools will make collaboration easier, and you won’t have to adapt to the style of the person who created a particular file.

Frameworks can also be useful tools for wireframing and prototyping, especially when there are time constraints and you need to put something in front of users or stakeholders quickly.

There are differences between a framework and a patterns library, components or even a simple collection of code snippets. A framework is a system that is flexible and can be adjusted to a myriad types of layouts, creating various page templates, whereas a library constitutes smaller individual modules that don’t have to be tied to any particular overarching framework or page construction.

A pattern demonstrates how, for example, tabbed navigation should function or how to mark it up; a design component could be the exact visual representation of an instance of tabbed navigation, with its colors, shapes and fonts. This explanation of these two distinct and important concepts is very simplistic. The “Further Reading“ section at the end of this article lists some useful resources on both.

The Yahoo Design Pattern Library.

A framework doesn’t have to spit out numerous unsemantic class names to every container in your markup. If you are creating your own, you are free to name those classes whatever you feel is right.

Let’s imagine you are starting to write a framework that can be shared across various development teams in your news organization. You might start with the following skeleton:

/* Resets */

/* Structure */

/* Global elements */

/* Visual media */

/* Article structure */

/* Forms */

/* Tables */

/* Reusable */

This structure is probably similar to many of your own style sheets. Let’s look at the “Article structureâ€� section as an example of something that would probably benefit from some framework inspiration. In the project, you will probably have to accommodate several variations of templates from various departments, sub-departments, content creators, editors, etc. Rather than using classes like span-6 and pull-3, you can define a naming system that better ties into the website’s content. For example:

/* Article structure */

article {
	width: 80%;
}
article.charticle { /* Charticle pages have no sidebar */
	width: 100%;
}
article.listicle {
	width: 70%;
}

article > .headline {
	font-size: 2em;
}
article.feature > .headline {
	color: #000;
}
article.breaking > .headline {
	text-decoration: underline;
}

article > section {
	border-bottom: 1px solid #efefef;
} 

article > aside {
	background: #efefef;
	padding: .5em;
}

article > footer {
	font-size: .9em;
}

Several things about the above CSS could be debated (I’m sure many of you have strong feelings about descendent selectors and named elements and even whether some of these classes could have been simple element selectors — to name but a few points), but none of this matters in this example. What does matter is how you can be influenced by what popular do-it-all frameworks are doing, and how you can apply that to your clean, semantic and perfectly named markup and CSS.

If you can plan for and analyze the needs of the people who create the content, then you can ensure that they have the flexibility they need to do their jobs and that you can be proud of your code. Sometimes an extra class is necessary, but if that makes everyone’s life easier, then why not, right?

Think of Others

Following what we discussed in the previous section, the fact that your CSS doesn’t live in a vacuum can be extremely useful.

Other people — and the future you — might need to come back later on to edit the style sheet that you’re creating today. Wouldn’t you want your future self to be free to go home to your spouse and kids earlier on a Friday afternoon rather than have to stay up late refactoring a CSS file that is hard to comprehend and impossible to extend?

Do yourself and others a favor by considering what you’re doing. Add comments to your CSS files for such things as the following:

Calculations
Font sizes (especially when dealing with ems) and layout measurements are great candidates for these types of comments.

h2 {
font-size: 18px;
line-height: 1.167; /* 21 (original line-height) / 18 (h2 font-size) */
}

Hacks
On the rare occasion that you use a hack, explain what you’re doing, refer to the hack by its common name, and link to an online reference that explains what you’ve just done.

aside section {
float: left;
width: 50%;
display: inline; /* fixes the double float margin bug on IE5/6. More on this bug/solution: http://www.positioniseverything.net/explorer/doubled-margin.html */
}

To-dos
Even CSS documents have “nice to haves,� so listing what you’ve been planning to do but haven’t gotten around to yet might be a good idea.

/* To-do
Change all colors to RGB format.
Sanitize reusable classes section.
*/

File structure
Summarizing what is contained in a particular file can save time when someone is looking for a certain selector.

/*  Table of contents
Resets
Structure
Links
Typography
Small screens
*/

Dependencies
Is this file being imported by some other file? Does it override something else? Explain what and how.

/* Christmas style sheet 2011

Overriding: main.css
Importing reset file: reset.css */

The fact that CSS comments are not standardized could cause a problem with all of this preparedness: everyone does them differently. In my quest for the ideal CSS formatting style, I discovered the dusty CSSDOC standard, which tries (or tried) to introduce some kind of sanity to the situation.

The old dusty CSSDOC website.

CSSDOC is an adaptation of Javadoc (a documentation generator that extracts comments from Java source code into HTML). It is also similar to PHPDoc, Javadoc’s adaptation for PHP. A comment that follows the CSSDOC format (a “DocBlock�) looks like the following:

/**
 * Short description
 *
 * Long description (optional)
 *
 * @tags (optional)
 */

Every block starts with /** and ends with a space followed by */. Every line must start with a space followed by an asterisk. The tags may contain information such as @author, @copyright, @todo and so on.

The CSSDOC standard suggests that a CSS file should include a comment about the file itself at the top, containing meta data that is relevant to the whole file. This comment should include information such as the title of the document, a description and tags such as @project, @version, @author, @copyright and even @colordef, indicating which colors are used in the file. The file comment may be followed by any number of section comments that divide the style sheet into relevant blocks. Section comments include the tag @section:

/**
 * Typography
 *
 * @section typography
 */

The CSSDOC documentation is not lengthy. Also, it hasn’t been maintained for a while, but I did find it interesting and have started applying it to my projects because it takes some of the guesswork and subjectivity out of comments.

Another way to make sharing documents on a team easier is to standardize the style. We all have our preferences on how to format CSS, how to name classes and IDs, address bugs, etc. Creating a style guide that recommends a way to do these things in your company will make it easier for anyone who edits the CSS to dive straight into what they need to do, rather than having to decipher someone else’s style.

This may be overkill for a team of one or two, but it can improve efficiency and save time when the team grows. In this case, consistency should have final say; personal preference is not important. If you’re the only one on a team of 12 who prefers single-line CSS, you will have to take one for the team. (Pardon me if I sound bitter; perhaps I still recall what happened on my own team…)

Here are some examples of style guidelines:

• “Class and ID names must be lowercase.â€�
• “Do not specify units for values of 0 (zero). They are unnecessary.â€�

When creating a style guide, include a succinct explanation for its inclusion, otherwise it will be easy for people to challenge it. The BBC has some great examples of guidelines that are relevant to CSS authors.

An example of CSS guidelines, part of BBC’s “Future Media Standards & Guidelines� documents.

Learn About Object-Oriented CSS

Object-oriented CSS was started by front-end performance consultant Nicole Sullivan. The methodology brings modularity and flexibility to CSS by forcing you to create small flexible style sheets.

It follows two main principles. First, it states that an element should behave predictably, no matter where you place it on a page. So, a child element should behave the same independent of the parent, and parent elements shouldn’t need child elements to render correctly.

The second principle is that the rules that control the structure of elements should be separate from the rules that control their skin.

So, if you look at the pages that you need to build in a modular way and think of individual objects first and the pages second, then after creating the initial CSS you should be able to build any page layout using just the existing modules.

All of this sounds great, but object-oriented CSS does have some drawbacks.

For instance, in order for an element to be adaptable enough to be placed anywhere on the page, the name of its class should also be flexible. If you style a box and give it a class name of footer, and later on you decide to apply that style to a box in the sidebar, then the initial class name you gave it will be wrong — it’s not flexible enough. Thus, class names in style sheets that follow object-oriented CSS can sometimes be less content-driven or less semantic than we’d like.

Despite its drawbacks, object-oriented CSS has its value in certain situations. If we are working on a big website for which a small style sheet (small file size) and flexibility and maintainability are important, then following the principles of object-oriented CSS can bring huge improvements to our processes and huge savings to our company.

Once again, you don’t have to follow this methodology blindly in order to gain from its benefits.

Going back to the news company, let’s imagine you want to make a box that sits in the sidebar more prominent than other elements contained there. You might write the following CSS:

#sidebar .highlight {
	background: #efefef;
	border: 1px solid #000;
	box-shadow: 0 0 .5em #000;
}

#sidebar .highlight > h1 {
	font-weight: bold;
}

What’s so wrong with the CSS above? If you are following object-oriented CSS, then you shouldn’t restrict a style that you will probably reuse in the main content area by confining it to the #sidebar container. In our example, though, we’ll happily keep the descendent element selector in the second rule (object-oriented CSS advises against child elements being dependent on parent elements, but you can draw the line on how closely to adhere to a particular technique as you see fit, and that’s the beauty of it!).

So much more could be said about this technique. It is indeed well worth looking into, all bias aside. You will read things that you probably don’t consider good practice, but remember: context is important, and your expertise equips you to adopt the principles that will help you in your situation.

Step Into Programming

The command line is a boundary between designers and developers that we designers usually don’t want to cross. Instructions on opening the terminal can be quite intimidating for designers if they’re not familiar with it. I confess I’m guilty of steering clear of it most of the time.

But consider this: we keep talking about how we should learn and draw inspiration from the past — from print design, for example. We claim with pride to have deep knowledge of typography, color theory, layout, grids and scales. We see it as a requirement for anyone who calls themselves a professional designer.

This knowledge should be extended to encompass programming, at least at a basic level. After all, it is what powers our most precious creations.

Instead of being inspired by architecture — by its teachings, its processes and its vocabulary — why don’t we get inspired by the architect’s example, by what they have to learn? Why not be inspired by the multitude of disciplines that an architect has to know intimately in order to be a great professional?

How many disciplines can you spot in this model? (Image: n fiore)

Why not start now? Open Terminal. (Go on, don’t be scared. It’s only there to help.) Now type the following:

$ gem install sass

(You don’t have to write the $; it’s just there to indicate this is a Terminal command.) There, you’ve just installed Sass (which we’ll cover shortly). That didn’t hurt, did it?

If you’re working on a Sass file, you could type the following simple command to make the original Sass-formatted file automatically update the corresponding normal CSS file whenever changes are made:

$ sass --watch style.scss:style.css

The List Goes On

There are several more tools you can keep in your arsenal that can move CSS another step into the future.

Quite a few Web designers and CSS authors are becoming enamoured with CSS preprocessors such as Sass, which make it possible to extend CSS’ syntax to include, for example, variables, complex calculations and nested selectors. Not only do they enable you to use functionality not yet available in normal CSS, but you can increase efficiency by automating tasks such as updating a frequently used color on a file-wide basis, rather than having to change each instance by hand.

The increasingly popular Sass.

And with all the improvements brought by CSS3, even pure and simple CSS is becoming more powerful, enabling us to create very complex layouts and animations more easily and with fewer lines of code.

The list presented here is a short one, and I’d be happy to know what techniques you apply in your own projects to make the process of writing CSS more fluid and to make your style sheets smaller and more easily maintainable and sharable.

This Is Just The Beginning

Eric Meyer says, “You can’t identify a code craftsman by whether or not they use this framework or that language. You can identify them by how they decide which framework or language to use, or not use, in a given situation.� This statement couldn’t be closer to the truth. Discussing tools without context is pointless.

Saying that something is good or bad should be done in context. By deciding that a certain technique is fundamentally flawed because someone once said so, and holding to that opinion throughout your career without ever challenging it, is not what being creative is about.

In his Critique of Pure Reason, Kant says, “Have the courage to use your own intelligence.� I would ask you to set your biases aside when when speaking about tools, techniques and processes with other designers and developers who write CSS. Don’t view different opinions as a sign of ignorance or poor craftsmanship.

Certainly, we may question certain aspects of our jobs as Web designers, and whether to be more liberal in letting automation into our processes is just one of them — but one I’m particularly interested in.

I know and work alongside very intelligent and creative programmers. These are people who understand systems so complex that my brain shrinks every time it tries to even begin to understand them. These are also people who are proud of their work, true craftsmen of their times. I find it quite interesting how these two groups (CSS authors and programmers) work on the same products but in such different ways, how they both work with code but with such contrasting values.

There is a place for carefully handwritten, handmade, perfect CSS — I take great pleasure in this myself. But there is also a place for the study and perfection of a more mechanized approach to style sheets. Both can certainly run side by side.

What are your views on this subject? Have you been trying to automate any part of your CSS writing? Do you think style sheets should always be handcrafted?

Further Resources

Hopefully, I have linked to all of the resources used to write this article in the article itself. Here are a few more interesting reads that touch on this subject, if not in its entirety at least partially.

Front page image credits go to Creativity103.