Open source content management systems like Drupal and WordPress provide great tools for creating content types, adding fields, customizing field labels, and adding field-level help text that can essentially serve as built in content documentation for the site administrator. However they are only helpful if you use them.
A Quick Embarrassing Story
About six months ago I finished building a client’s site before they were able to finish creating the content for their new site. This is not an unusual scenario because almost everyone underestimates how long it takes to generate quality content. So, we let the client know their site was ready to go whenever the content was ready. Six months go by, the client finishes their content, and passes some of it along to us to enter into the system, as we agreed to do. Unfortunately, a site that was “ready to go” now needed module updates, it needed to be re-deployed, and it needed to be reviewed to make sure I understood how everything worked.
Our team scheduled a meeting and I showed up ready to demonstrate how quick and easy it is to add content to the site. I remembered it being a simple site (and it is); however, there were a few entity references that were not exactly obvious how they worked, at least not to me—the person who built the site (but has also built many other sites since). Long story short, I sat there with my co-workers for about ten minutes trying to reverse-engineer what I had previously created murmuring things like, “wait, no, that’s not right, sorry.” At which point we cut the meeting short so I could take some time to re-discover exactly what particular fields do on the site, document them, and write better help text.
Providing good labels, descriptions, and field groups is not a new concept for NEWMEDIA or myself, and I had a good(bad) reason why I did not add them… I never went through the process of preparing the site for training. Throughout the development process I tend to first focus on getting specific features and the site as a whole to work, with the idea I can later focus on optimizing it for a site administrator. The only problem was the client took longer than expected to get their content ready, which meant I did not prepare for training, which meant the fields did not have good descriptions, which meant I was forced to remember this great article about good field labels and help text and why they are important.
How Can I Expect Others to Remember When I Can’t?
Over the last seven years at NEWMEDIA I have trained over 50 sites to clients with varying degrees of technical ability. Before the training session even begins, I usually have an idea of what the difficult content types or fields on the site will be for a site administrator to understand and remember. These are usually something like a field that drives content or features across multiple areas of the site, but is populated on a content type that does not seem related to where the content may appear. For example, you may have an image field that appears full size on the News page where it was created, which is then a thumbnail on the landing page, and then another size on the homepage. All the user needs to do is upload one image and everything will take care of itself, but after time they may not remember how it works, someone new may take over the site administration role, or it may not have been very clear to begin with.
As a trainer I can go over this point slowly and clearly, put it in the training document, and record a screencast of the training session—all the while the person I am training is nodding their head telling me how simple it is and they can’t wait to start using it right away. The reality is they get busy dealing with urgent issues, weeks go by, and they don’t remember how to login to the site let alone how that image field on the news content type works. Now, instead of using the image field designed to display that image in all the places at all the right sizes, they fallback on their WYSYWIG prowess, upload an image in the main body field, wonder how they get the image to show up in the other places, unpublish or delete the article, and make a mental note to call the developer as soon as they get a few free minutes.
This scenario may not be completely avoidable, but there are some simple things we, as web developers, can do to help reduce the problem: we can include good field labels, good descriptions, and strategically group the fields.
This seems like common sense, so why does this even come up as a problem? It’s simple time, budget, habit, and assumptions. It is not that the development team does not think that good descriptions are helpful, it’s that there is usually a limited amount of time and budget and we are trying to give the client the most bang for their buck. It does not make sense to fine tune labels and descriptions if a key feature, and maybe the primary purpose, for the site is still buggy. In fact, much of the heavy lifting for good labels, descriptions, and fields groups can be solved before the CMS is even installed.
Enter the Build Spec
At NEWMEDIA we put all our content types and fields into a build spec. The build spec allows for field groups, labels, and help text to be defined upfront so we don’t have to spend a lot of time thinking about the perfect description, which can derail the developer’s workflow and distract them from the overall task of building the site. Plus, the developer may not be the best person to write the description or provide the label. The developer has a very good sense of the site and may write descriptions that are not as meaningful to someone unfamiliar with the site, or we may just assume it is obvious what the field is used for and a description is not necessary. The good news is the build spec is just a spreadsheet so it can be modified by someone other than a developer—a project coordinator, content strategist, or anyone who understands how the fields are designed to be used on the site. In fact, someone who does not understand the fields as well as the developer may be a better candidate for writing meaningful descriptions and labels.
While the build spec may not fit into your development process, I encourage you to think about the field labels and descriptions early in the process. It’s fine if they need to be re-written or re-worded a bit prior to training the client. At least they will be there throughout the development for other developers, project managers… and yourself.
Bad Help Text
Better Help Text
