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.
The tutorials are designed and developed for new users. Unique terms
are explained, concepts are presented visually, and procedures are simple and
However, new tutorials are planned other roles and products.
Introductory tutorials, Learn the Basics, include:
Intermediate tutorials, Beyond the Basics, include:
More tutorials coming soon
If you have questions or suggestions, post your thoughts here.You can also submit feedback directly from each tutorial.
Social Business User Experience blog
DeAnna Steiner 110000KQ1F DESTEIN@US.IBM.COM Tags:  portal-v8 getting-started portal 1,746 Visits
Jeff Schering 270000260U firstname.lastname@example.org Tags:  progressive_disclosure help documention embedded_assistance 1,465 Visits
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!
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:
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 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 (
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 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....
A form label labels a form field. Every form field needs one.
Form labels are created using the
<form> <label for="phone">Phone Number:</label> <input id="phone" type="text" /> </form>
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.
<div role="dialog" aria-labelledby="header"> <h1 id="header">Share Something</h1> <div> content goes here....</div> </div>
aria-describedby - uses one element to describe (rather than label) another. The same element can also describe multiple objects.
A good use of aria-describedby is for tooltips (not the HTML ones created using the title attribute, but home-grown ones we create) or other kinds of help text, like help text for a form.
<form> <label for="phone">Phone Number:</label> <input id="phone" type="text" aria-describedby="phoneHelp" /> <div id="phone help">Enter your phone number without any formatting. Just the digits, please!</div> </form>
That's it. A quick description of labels. It's not that hard, but labels are great enhancements to the usability of web sites, so they are important to get right.
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.
(Apologies to Jerry Maguire.)
Three ways to give us feedback:
Are you an IBM Connections expert, or do you know someone who is?
We are looking for residents for an upcoming IBM Redbooks residency. Details are here: http://www.redbooks.ibm.com/residents.nsf/Residencies/LO-2W04-R01