Social Business User Experience blog

Labels are very important for making your website universally usable. The different types of labels you need to pay attention to when designing and coding web applications are:

Alternate text for images

Tooltip text

Form labels

Aria labels

Lets get into the details....

Alternate Text for Images

Alternate text is for a screen reader user. If you leave it off, the screen reader reads the image name which is not very helpful to a blind user if your image is named something like "img001_110112.png."

Alternate text is defined in the alt attribute of the html img tag, as in alt="file" if the image is a file icon. Thus, it is more commonly known as "alt text."

Alt text also shows up if the image is missing (or images are turned off by the user).

Internet Explorer kind of complicated things by also showing this text as a tool tip when you hover over the image. Nice feature, but really the title attribute is for tool tips. No other browser shows the alt text as a tool tip, so don’t even think of alt text in this context. (In case you’re wondering - I know you are - if an image has alt text and title text, Internet Explorer will do the right thing and show the title text as the tool tip.)

How then, should you think of alt text? Here is an easy-peasy rule of thumb:

If your image conveys information to the visual user, define alt text for it. If your image is just eye candy for the visual user, alt text should be null (alt="").

Eye Candy - the user doesn't need to hear Gail Chao's name twice, or that she has an associated photo that they can't see.

<img src="myPhoto.jpg" alt="" /> Gail Chao

Added Information - the user will know that clicking on the link will launch a spreadsheet

<a href="#"><img src="file.jpg" alt="spreadsheet"> Latest Budget</a>

Alt text always needs to be set, even if it’s alt='" because, remember, otherwise the screen reader will read the image name. If alt text is set to null, the screen reader will skip right over that image and go on to the important stuff.

Tooltip Text

Tooltip text is set via the title attribute of an element. It shows up when a user hovers over the element after a slight delay. This is built into the browser.

<img src="delete.png" title="delete" />

(user will see the tooltip "delete" when they hover over the delete icon)

Tooltip text will not show up when the user focuses on an element. This is a problem for keyboard-only users. The bottom line is that tooltip text is not universally usable. It is only available to mouse users. So if you need to convey information to the keyboard-only user (like tooltips for icons) you should use a custom solution to create your own tooltips.

Not sure what the browser manufacturers were thinking and why they haven't fixed this by now....

Form Labels

A form label labels a form field. Every form field needs one.

Form labels are created using the <label> tag and are assigned to form fields using the "for" attribute which maps to the id of the form field.

ARIA Labels

The new kid on the block is aria-label and its sister aria-labelledby and cousin aria-describedby.

aria-label - allows you to label any element in the HTML. A screen reader will give aria-label priority and read it even over the text inside that element.

e.g.

<div role="nav" aria-label="primary"> menu items go here...</div>

aria-labelledby - allows you to use one HTML element to label another. It is preferrable to use aria-labelledby over aria-label whenever possible.

For instance, with ARIA you would put role="dialog" on the outermost HTML element that makes up the dialog. Then you could use the aria-labelledby attribute to point to the HTML h1 element as the label.

Getting Started with Your Web Experience is a collection of tutorials for IBM
WebSphere Portal and Web Content Manager. Two levels of tutorials guide users
from basic to more complex information. Each tutorial has a Next steps topic to
guide the user to the next level of information.

New administrators

The tutorials are designed and developed for new users. Unique terms
are explained, concepts are presented visually, and procedures are simple and
prescriptive.Currently the primary audience is administrators that are new
to IBM WebSphere Portal and Web Content Manager.

We provided a printable PDF with each tutorial, so you can jot down
notes as you go through the tutorials. Find the PDF in the table of contents for
each tutorial. Look for the Download Tutorial as PDF link.

Some tutorials include supplemental information such as check lists
and reference cards. The supplements are designed to record your decisions for
future reference.

Suggestions

If you have questions or suggestions, post your thoughts here.You can also
submit feedback directly from each tutorial.

In the technical writing world in general, and at IBM in particular, writers are becoming more involved in the software design and development process. We're beginning to embed product help directly into the product UI. Our goal is to eliminate the need for our clients to interrupt their work and go looking for help. No longer will separate, independent documentation be the only content that we deliver. The techniques that we use are Progressive Disclosure and Embedded Assistance.

IBM's own Andrea Ames presented these techniques to the Society for Technical Communication summit in May 2012. A blog post by Sarah Maddox (http://ffeathers.wordpress.com/2012/05/23/stc-summit-day-2-progressive-disclosure/) gives an overview of what Andrea said. I'm not going to give a summary of the summary; you can read Sarah's post yourself. But what I will do is give a quick example of what embedded assistance is and how it can make using software easier by delivering information when you need it and where you need it.

For example, in SmartCloud for Social Business, when you start a Community you must choose one of the access options. The options are Restricted, Moderated, and Open. In the old way of doing things, the options would be simply listed. But what do these mean? How do you choose? In the old way, you would have to first find the documentation, and then find the section in the documentation that contained the information. And that's if you even bothered to look; most of us would probably pick the best-looking option, cross our fingers, and hope for the best.

The new way is to add text to the option so that now you can quickly decide the type of access that you want for your Community. The options, as shown in the graphic below, are Restricted (people must be invited to join), Moderated (anyone in my organization can see content but must request to join), and Open (anyone in my organization can join).

Help should be easy to use, easy to understand, and easy to find, and there's nothing easier to find than text right there on the screen.

And although we've made a good start at this, we still have a ways to go. For one thing, it's a whole new way of working. Writers must work with the UX people to make sure that our content has a place, and also work with the developers to get the changes implemented. And like any new way of doing things, the transition is not without its challenges. People who are accustomed to working alone are now working together. Where before we only had to confer with colleagues who were familiar with our own domain (because writers spoke with other writers, designers with other designers, and developers with other developers), we now have to speak to each other. And lets face it, designers and developers are just plain weird. They would no doubt say the same about writers.

But on the other hand, we all learn new things, and because of this our jobs are far from tedious. We also learn the problems and issues and stumbling blocks that our counterparts face in their day-to-day work. And there's a thread that binds us; we all have ambitious plans and tight schedules, and we all feel a little down when the schedule is just a little too tight or the plan just a little too ambitious, forcing us to let something go until the next release.

Overall though, for me this is a welcome change in my job description. Not only do I get a chance to influence the design of a product and the way that a product works, but I also get to think more and write less. And I like thinking!

Working
in documentation can be a frustrating experience sometimes, for
reasons you wouldn't really expect. I used to think that it would be
hard to accept criticisms about our work. I envisioned customers
coming in and pointing out all the flaws in work, and us having to
scramble to address them.

It
turns out that the reality is just a little bit different. You see, I
sit here most days wanting solid feedback that I can act on. Where do
the docs need work? What parts are confusing, and why? How are people
looking for the info they need? If you answer those questions, I can
do a better job of providing information that will actually help you.

But
more often than not, what I really get from users is sweeping
statements like, "The docs are horrible" or "You need
to make section X better." Honestly, most times I'd love to make
section X better, but I'm frequently left wondering what's actually
wrong with section X in the first place. How did it fail you? Where
are the problems? In your mind, what could be better?

So
there's the dilemma. We want feedback, we welcome feedback, and we
even go out of our way to seek feedback. But oftentimes that feedback
doesn't really help us, because to take any kind of meaningful action
we need the feedback to be specific. The best feedback points out
specific issues, tells us where you got confused, or points us to
something you think is better so that we can compare.

Not
sure how to give us this kind of feedback? Take a look at the end of
this post for some helpful hints, but my suggestion is to start with
the product wikis. You can comment on specific articles to tell us
what works and what doesn't, and you can even edit them yourself if
you're so inclined. We'll roll those edits right into the product doc
if they make sense to us.

So
let me wrap this up with a simple plea: Help us help you. Please,
make your feedback specific.