This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. On Tuesday I attended two sessions on HTML5. The first was a presentation by Scott DeLoach, called “HTML5 to the Point“. The second was a hands-on session run by Char James-Tanny, called “60 minutes to an HTML5 Web Page“. This blog post is derived from the notes I made during those two sessions. If you find any inaccuracies, they’ll be mine.
First, here are my notes from Scott‘s session. He presented a lot of highly technical information. Thanks to his easy, clear way of presenting information, we absorbed it all.
Why is HTML5 important?
Scott introduced his topic by telling us about the organisations that are already using and indeed driving the adoption of HTML5:
- According to W3C, HTML5 is the future of the web. It will replace the existing versions of HTML and XHTML.
- Adobe are working on “Helium” (we’re not sure exactly what this is yet) and “Wallaby” (allowing you to save Flash files as HTML5).
- Facebook will be spending the bulk of their investment and development on HTML5 this year.
- Google is hugely into HTML5. Leading the way. The Google Instant search uses HTML5. Gmail is coded in HTML5. See their site HTML5 Rocks. Some of their features work only in Chrome, but others work in other browsers too.
- Microsoft: Bing is using HTML5.
- Apple rewrote all of the Apple website in HTML5.
- YouTube: Video is one of the biggest parts of HTML5, and YouTube are moving their video format to HTML5.
- Netflix is moving to HTML5. The conversion is almost complete.
Converting to HTML5
Scott listed the basic steps required to convert a web page to HTML5:
- Use the HTML5 doctype.
- Replace HTML elements that are no longer supported in HTML5. Some of the features that have been deprecated for a while are now not supported.
- Prepare to support older browsers (requires a bit of trickery) and mobile devices (easy).
- Use the new structure elements provided in HTML5. Take advantage of the new tags to structure your documents.
- Use the other new features. There are some really cool things you can do. HTML5 offers a combination of standardising the things we’ve been doing anyway, with some new features too.
The HTML5 doctype
They have simplified the format of the doctype statement that you put at the top of your file.
At its simplest, it’s just this:
For the more extended format there are two options, an HTML syntax and an XHTML syntax. The difference between the two is tiny, just in the format of the quotation marks. You can choose either one.
Scott showed us a list of elements that are no longer supported, and their HTML5 alternatives.
The list is fairly long. Here are just a few specific examples:
- center – use CSS (text-align:center)
- frame, frameset, noframes – use an iframe or CSS (float properties)
- noembed – use the “video” element
Supporting older browsers
Scott pointed out that we will need to support older browsers, and in particular IE 8 and earlier. (The latest version of IE, which came out yesterday, has much better support.) Scott gave us some tips:
- There are a number of new elements that the old browser will not recognise. You will need to add a style definition for each of the new elements, that the older browser can pick up. Examples of such new elements: article, aside, canvas, details, etc.
- Test your pages in the old browsers.
- Create styles specifically for older browsers.
- For older versions of IE, use Remy Sharp’s script to enable all the new elements in older versions of IE.
Supporting mobile devices
Most browsers for mobile devices (generally Safari and Chrome) support HTML5.
Structuring your documents
This is one of the biggest changes, and also most interesting to technical communicators. You can use the new elements in HTML5 to structure your documents more easily.
Scott listed all the new elements, and homed in on a few examples:
- header – A logo and page title.
- section – A collection of news articles. You can nest sections. Note that if you do that, the heading levels may change automatically. For example, let’s assume that you nest section B inside section A. If section B has an h1, that h1 will change to h2.
- article – A blog post or news article. Scott pointed out that section and article have a lot of overlap. This will probably confuse people. An article is something that can stand alone. A section does not really stand alone.
- aside – Scott mentioned that this is a good placeholder for “related topics” links.
Scott showed us a neat diagram illustrating how each of the above elements might fit into a page. Then he dragged the elements around, showing how flexible the structure is. It’s largely up to you, how you use the elements to structure your page.
Including video and audio is a lot easier, using the “video” and “audio” elements.
The “canvas” element is really cool. It creates an area for images and shapes. It’s an alternative to having a graphic, a way to draw shapes (squares, circles) using code. You can have elements of the graphic animated or move around.
The “ruby” tags add pronunciation guides to content.
The “wbr” tag offers an opportunity for a linebreak. If a linebreak is necessary, the browser can make one.
New global attributes
Scott mentioned a few of the new attributes available in HTML5:
- It’s easier to make menus via the “contextmenu” attribute, which creates a popup menu.
- “draggable” allows an element to be moved.
- “spellcheck” checks the spelling in the element.
Scott discussed a number of new methods. I didn’t take detailed notes here.
Many, many new events
Scott said, what’s really great is that HTML5 standardises a lot of events that were previously supported only by specific browsers.
- onwaiting – you could provide some entertainment while people are waiting. 😉
- oninvalid – to provide an error message in a form.
- onoffline and ononline – you can tell people they won’t be able to find the information because they can’t access the web.
New form elements
Scott walked through a few of the new form elements:
- “required” to mark required fields on a form.
- Built-in validation for certain types of input fields, with built-in error messages. For example, if you specify an input field with ‘type=”email”‘, then the browser will validate the input content as an email address. At the moment, there are few browsers that support this option.
- You can also write your own custom validation and error messages for user input, using “input-pattern“.
For the rest of the session, Scott showed us some examples of the features he had mentioned.
- We saw the spellcheck in action. Pretty cool. The browser drew a squiggly red line under the misspelled user input.
- Including video, via the “video” element. Two great things in HTML5: It’s much easier to code the inclusion of the video, and you can also include multiple source files (for example, of different formats) so that the browser can choose the one it recognises. For mobile devices, for example, you can specify a minimum device width for your video. You can also include .swf files in the video element. If you include the attribute “controls“, the browser will include video controls too.
- The “ruby” element lets you provide pronuncation guides. The phonetic text appears directly above the word(s) bracketed by the “ruby” tag. Actually, Scott pointed out, the use of the tag is not limited to providing pronunciation guides. You could use it to provide a translation, or anything else.
- Determining the user’s location. Scott showed us a script that figures out your latitude and longitude. (He also has one that determines your altitude.) Let’s say a plumber is going out to fix a boiler. You can figure out which boiler they’re at and show them the correct “how to” video for that boiler.
- Using the new “editable” and “save” features in HTML5, you can let people annotate a web page.
Sample sites and other resources
Scott showed us a number of resources, including development applications, sample sites, recommendation sites and information about browser support.
I didn’t make notes of all the sites Scott recommended. I’m sure he’d be happy to provide them. 🙂 Here are just a few that he highlighted:
- Adobe Dreamweaver CS5 can write HTML5. So can CoffeeCup’s The HTML Editor 2010, and TopStyle 4.
- Scott recommends specifically the following two sites, written entirely in HTML5
- MTA.ME, a subway train visualisation.
- The Wilderness Downtown. Awesome, says Scott. It asks you to enter the address of the town where you grew up. (Just start typing the name of the town, anywhere in the world. The smart search will find it and prompt you!) It’s spooky. They go behind the scenes, using Google Maps, and put the location up on the screen. Then the action starts, with the guy running near the location that you specified! (Chrome browser recommended.)
Scott’s quick reference guide to HTML5
Scott has created a quick reference guide to HTML5, which he made available specifically to WritersUA attendees. He said it’s fine to include the link in this blog post 🙂 so here you are: HTML5 quick reference, a PDF document by Scott DeLoach.
Introduction to Char’s session
The rest of this post comes from the notes I took during Char‘s session. Char hosted a hands-on lab, where we built an HTML5 web page from scratch.
To start off her session, Char gave us some introductory information about HTML5 syntax.
HTML5 has a free-form syntax:
- Any case (upper, lower, mixed)
- Double quotes, single quotes, no quotes
- Close tags or no close tags
- Optional attribute values.
That’s all you need in your doctype element, to make a document HTML5!
The page structure is familiar to anyone who has created an HTML page:
<!doctype html> <html lang="en"> <head> </head> <body> </body> </html>
We started by creating a file “index.html”, containing just the page structure elements shown above.
Then we added the following code to the “head” element:
<meta charset="utf-8"> <title>I Need a Title!</title> <!--[if lt IE 9]> <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"> </script><![endif]--> <link href="css-wua.css" rel="stylesheet" type="text/css">
The first script element pulls in Remy Sharp’s script to declare the new HTML5 elements for compatibility with IE8 and earlier. This is the same script that Scott told us about, just hosted in a different location.
The second script elements includes a stylesheet, created by Char, to make things pretty.
For the rest of the session, we added the HTML body to create a simple web page. I haven’t included it in this post, because it’s Char’s work. Here is an online version of the page we created.
Thank you Scott DeLoach and Char James-Tanny for two interesting and authoritative sessions. I love Scott’s quiet, composed way of presenting so much technical information so easily. Char is absolutely great and guiding a motley collection of HTML5 wannabees through the fumbling stage up to producing a quality HTML5 page. It was useful to have Char’s session follow on from Scott’s. Again, what a great conference this is. 🙂
This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. These are my notes from the session called “Determining the Best Design Approaches and Development Tools for eLearning” presented by Joe Ganci. If you find any inaccuracies, they’ll be mine.
Joe’s presentation style is conversational, easy and comfortable. He walks right up to the audience, asks them questions and tells them personal anecdotes to illustrate his points.
First points to consider
There are four things to consider when determining your design approaches and your choice of development tools for an eLearning system:
- Talent – Who is your talent? Who does the work?
- Topic – What do you want to teach people, and who is your audience?
- Technique – What technique are you going to use to impart your information?
- Tool – Determine the tool or tools after all the other questions are answered.
For the rest of the session, Joe dived deep into each of the above points, and showed how your choices will influence the tools that you choose.
Who does the work? Consider these three groups of people:
- Instructional designers
- Subject matter experts (SMEs)
At the beginning of a project, the instructional designer creates a number of deliverables, including the storyboard, design document and analysis document.
Subject matter experts are well known to technical writers.
When considering the programmers, ask these questions: Who builds the eLearning in your organisation, and who should it be?
How does talent impact tool selection? SMEs, instructional designers and programmers will be using different tools. Joe showed us how the different groups of people are comfortable with different tools. For example, SMEs may use presentation tools like PowerPoint, instructional designers may use Camtasia, programmers use things like XML, HTML, Flash.
Looking at the information you want to impart, there are four key areas:
- Information (concepts)
- Technical information
- Soft skills (highly scenario-based)
Questions to ask yourself: Which of those information types are the most requested within your organisation, and who works on them?
How does topic impact tool selection? For informational topics, presentation tools like PowerPoint and Prezi are useful. For compliance topics, you may choose Camtasia or Lectora. For technical information, something like Raptivity, SmartBuilder. For the soft skills, you need a lot of computing: XML, HTML, Flash.
Joe discussed four kinds of technique in eLearning systems:
- Tell me
- Show me
- Let me
- Test me
Moving from top to bottom of the list, these techniques require an increasing level of complexity in the instructional design.
Questions to ask: What techniques are your favourite for eLearning, and which techniques do you want to implement next.
One of the audience members said he prefers a combination of “show me” and “let me”. Joe agreed. You don’t want to overdo the “let me” side of things.
It’s sometimes a good idea to be able to present each candidate with a slightly different experience.
When testing the student, one technique is to set up a pool of questions, and have Captivate randomly select questions out of the pool. You can base the pools on level of complexity, to ensure that each candidate gets the same overall level of test.
Essential questions for determining your design approach
Joe took us through each of the following questions that we need to ask, and discussed the various options for each.
- What is the content? (Your objectives, lesson plan, time available to the learner, existing content that you can base yours on.)
- Who is the audience? (Age, prerequisite knowledge, language, culture, disabilities, educational level, and so on.)
- How will you design the material? (Rapid prototyping, or the traditional instructional design approach, or a combination of the two.)
- What is necessary for the design? (How much time is necessary, do you need a video, do you need audio, how much text is required, how much interactivity, and so on. A number of the answers depend on you audience as well as the topic. The answers to these questions affect your choice of tool.)
How does technique affect tool selection? For “tell me”, the presentation tools like PowerPoint are effective. For “show me” and “test me”, you may use Smartbuilder and similar tools. For “let me”, you will need HTML, XML, Flash, and so on.
Questions to consider: What tools are available to your organisation, and what tools do you know? You need to consider also how well you know a tool, and whether you know everything that you need to know.
There are a number of tools, and many of them do similar things. But they don’t all work the same way. There are some really good surveys out there. Joe pointed out the survey of the Top 100 Tools for Learning 2010.
Interestingly, the tools at the top of the list are things like Twitter, YouTube, GoogleDocs – social and informal learning tools.
As a trend in the next 3 years, Joe sees more and more hand-held platforms.
How does all this affect developers of eLearning?
We will be basing our work on the known foundations, but we’ll be looking at new ideas and techniques too.
An example of eLearning developed by Joe
Joe showed us an eLearning tool that he created in Captivate. It’s aim is to train hotel clerks in dealing with conflict. It’s available on the web: Hotel Clerk Training, Dealing with Conflicts. (Make sure you have audio enabled on your computer.)
It’s pretty cool. You can hover over each person, such as the manager or coworker, to see what each person says when you (the clerk) ask them what to do.
There’s a bit of humour in it, especially in the acting on the video segments – enough humour to make you smile, and enough to make you sympathise with the people.
When the user chooses the right response, the system responds with some jubilant animation to reward them.
Why is this type of approach better than PowerPoint? The student who is already an expert can fly right through the lesson without wasting time. A novice can explore all the answers in full. It’s also more interesting and more engaging. An experience as close to real life as possible is more likely to put the learning into your long term memory, as opposed to short term memory.
Thank you Joe for an interesting and engaging approach to the choice of tools for eLearning. It’s very useful to see how our decisions can affect the tools we choose, and how indeed we should make other decisions before deciding on a tool. I love the hotel clerk training tool!
This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. One of the sessions that I attended today was an Adobe lab, run by Scott DeLoach, Kevin Siegel, Laurie Edelman and others.
During the conference, there were a number of “lab” sessions. The labs offer a number of computer workstations and software that we could use for hands-on experimentation. A few experts wandered around offering help and advice.
My aim in attending the Adobe lab
I decided to take a look at the latest version of RoboHelp. I have used RoboHelp extensively in the past, but not since RoboHelp 8.
In particular, I wanted to explore the new features in RoboHelp that allow you to gather feedback from users, and allow users to share comments among themselves. I had heard and seen this demonstrated in various places. The idea is that you have an online help system, shared amongst your users, even installed individually on their machines. Each user can add comments to their own version of the help, and share those comments with other users via a central server.
Exploring RoboHelp’s comments feature
In the lab there was no RoboHelp Server available, so we could not see the server side of the functionality in action. But I did manage to explore how it would work. Here’s what I did.
In RoboHelp, create your online help topics as usual. For the lab session, I used one of the sample projects supplied by Adobe.
The next step is to generate your help output, selecting Adobe Air as your output format. The Adobe AIR output is the only format that supports comments submitted by users. To generate the AIR output:
- Choose one of the a “single source layouts” available. A single source layout basically corresponds to an output format. For this lab session, a few Adobe Air layouts were available. I chose “Adobe AIR – Role Based”.
- Double-click the layout in the “single source layout” window. You get a popup where you can configure various options for the chosen layout.
- On the “General” tab, choose an “Output Type” of “Adobe AIR Application“. This is the only output type that will allow comments from users. The other output types are hybrids that weave a Flash solution into an HTML web-based help system.
- You will need a digital certificate. If you don’t have one (which is likely at this point!) you can generate a self-signed certificate for use while testing. Eventually you will need to get a certificate from a real certificate authority (CA). To generate a digital certificate, click “Create” next to “Digital Certificate”.
- Supply a publisher name of some sort.
- Specify a password for the certificate.
- Next to “Save As”, specify a path and name something like “C:\cert.p12”.
- Click “OK” to generate the certificate.
- Click the “Collaboration” tab.
- Select “Enable Topic Rating”, “Enable Commenting” and “Enable Comment Moderation”.
- Set a password that the comment moderator will use.
- At this stage, it would be good to specify the RoboHelp server to enable server-based storage and sharing of comments. I could not do this during the lab, because there was no RoboHelp server available.
- Click “Save and Generate” to create your online help system.
- Click “View Result” to see the resulting help files.
The AIR application will start up, showing your help topics in the help system. Now you want to add a comment to a topic.
- Click the comment icon near the top left of the screen. (The icon looks like a couple of comment bubbles.)
- A comment area will appear at the bottom of the topic.
- To add a comment, click the plus sign.
Adding a comment:
Comments are displayed in reverse chronological order:
This looks pretty cool. As far as I could see, there’s no opportunity to add graphics or formatting to the comments. They’re plain text. Also, they’re not threaded – you can’t reply to a specific comment. Still, once a server is hooked up it is pretty cool for people to be able to share comments from their desktop apps. I’d be interested to see it in action, and to hear any experiences other technical writers may have had with this feature.
This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. These are my notes from the session called “Hotrod My Help” presented by Leah Guren. If you find any inaccuracies, they’ll be mine.
Leah’s presentation style is both informal and professional. She started out by introducing herself as “this deranged woman”. She then became more serious quite quickly. Her talk was about design of online help systems. She used the metaphor of hot rodding – talking about the paint rather than what’s underneath.
Introducing the topic
Leah’s talk was entirely tool agnostic, and described techniques that we can apply to our documents with very little effort.
Nevertheless, Leah pointed out, this stuff matters for a number of reasons:
- Design should match the subject matter.
- Better design improves usability.
- We’re not talking about making things look pretty. We want to make sure that what we develop will communicate as effectively to users as the words we choose.
- When people see help with a sloppy design, they’re less likely to trust the information.
- Design should support the meaning of the content.
- It should make it easier for people to find what they’re looking for, to recognise it and to use it.
Leah also pointed out that if your readers are noticing the design, then you have made a mistake. (As a side note, I tweeted this point and received an interesting reply from Bill Kerschbaum.)
The design concepts
Leah introduced us to some design concepts, the jargon. Mastering the terminology lets you defend you choices with more authority.
Leah introduced us to the acronym PARCH:
- Proximity – When elements are close together, we recognise that they are related.
- Alignment – Choose where you position elements on the screen, to develop a meaningful design.
- Repetition – Repeated visual patterns help people to access and remember the information efficiently.
- Hierarchies and dependencies
One stylistic mistake that violates this principle is the “floating heading”. That’s when you have a heading with the same amount of space above it as below it. Instead, there should be less space below the heading, to bring it closer with the content it describes.
Use alignment for a less sloppy design.
Consider things like colours, icons, placement. Stylistic repetition reinforces the information for the user and gives them more confidence.
We need contrast so that people can see the differences in meaning between different elements on the page. For example, links should look different from other text. So should headings, and layered information. The rule of contrast is that it must be meaningful. Readers don’t care how you do it, whether you use a list or headings or bold text. Just be consistent and make it meaningful.
This defines how elements of information on the page are related to other elements on the page. Consider the use of white space and indentation.
Other concepts and techniques
- White space – Consider margins, space between lines, hanging indents, paragraphs etc. White space is critical. If you don’t have enough white space, the text is not readable. Users flee from densely-packed screens.
- Plumb lines – Draw vertical lines at every point where an information element starts, to make a clean design. Good clean design steps into the background. Bad design is noisy.
- Indents and text wrap – Indents help the concept of contrast. Good examples are bulleted lists.
- Paragraphs – Leah recommends the following design techniques for paragraphs, to enhance readability:
- Flush left, ragged right.
- Single line spacing.
- White space between paragraphs.
- Chunking – Use white space intelligently, to show the logical visual chunks of information.
- Nesting – Nesting relates to hiearchies and logically related information. Leah mentioned “illegal” nesting. The rule in technical communication (a tacit contract with the user) is this: if I’m going to break the information down into logical categories, there must be more than one category. For example, you can’t have just one item in a bulleted list, or just one level-2 heading.
Examples – applying the concepts
After introducing all the theory, Leah moved on to examples of web page makeovers, using her hotrod metaphor. She took us through some real documentation and web pages from various sites, and applied her principles to each one.
These are some of the mistakes she fixed up:
- Messy text.
- Dashboard that was not designed to be meaningful.
- Screenshots taken without care and without tidying up afterwards.
- Sloppy text wrap, that probably happened when pasting content from elsewhere.
- Inconsistency in capitalisation, punctuation, and so on.
- Long lines that force the user to do horizontal scrolling. A typical culprit here is information in tables. This is easy to fix, but easy to overlook.
- No visual cue that content continues below the fold. Readers may think they have reached the end of the steps, without realising they need to scroll down. One way to fix this is to include a “Start” and “End” icon.
- Help window opening on top of the application by default. The solution is to make the default opening position at top right, for example.
- Concordance (repetition of same words) in the table of contents (toc). This is very distracting. If the toc entries are very long, people will not see the meaningful bit in the toc window.
- Use of blue (usually used to denote hyperlinks) as an emphasis or point colour.
- Too many layers of hierarchy (too much nesting) in a table of contents.
- Links in the text. Don’t put links in the text unless they’re popups or dynamic HTML. Keep all links off to the side or at the bottom. People get distracted by links, or click them and get lost.
- Empty topics.
Help authoring tools
If the problem we’re addressing lies within a tool that we use to develop help systems, then the HAT and DITA tool developers need to fix it. We need to be involved in the design of such tools.
Throughout the presentation, Leah had “bonus rounds” where she asked us to name concepts that the pages were violating. She promised us “valuable prizes” (said with a grin) which we could collect afterwards. This was great for getting audience participation going.
Thank you for a lively session, Leah!