Sandra Earl's List: Writing

• What we consider to be good technical writing often reflects an American cultural perspective. One facet of this cultural orientation is that technical writing tends to use a low-context style. Most notably, we tend to write user assistance as if users have never seen the user interface we are explaining. Secondly, we tend to write user assistance as if users have never even used software before. But users rarely go to Help before they have tried to accomplish a task on their own first, and most users today have extensive experience using software and are familiar with the standard ways of interacting with user interfaces. So a user interface is a high-context artifact—one a user has already seen before reading our documentation and that uses rules and conventions the user already knows.
• My point is that a user who is defining a policy and encounters a Comment text box is not going to sit and wonder who fills it in. Yet we tend to document such elements as though they would.
• A further advantage of moving to a high-context style is that we can eliminate interaction verbiage that does not add value, such as “Select the…” from descriptions of drop-down lists, radio buttons, and check boxes; “Click the…” from descriptions of command buttons; and “Type the…” from descriptions of text boxes. In high-context writing, we can assume prior exposure to conventional user interface interactions.

• Here are some guidelines for high-context writing as it applies to user assistance:

   
   
  • If the subject is obvious, do not restate it. Sentence fragments should abound in descriptions of user interface elements.
• Just because one or two elements in a user interface need explanation does not mean you must explain every element.
• Context-sensitive Help topics and messages should assume a reader is coming directly from the user interface and, therefore, should use a high-context style. If users get to Help through an index or table of contents rather than from the interface, they are not reading to do, and the how-to topic isn’t really for them anyway.
• In addition to the obvious need to write user assistance in a high-context style, we should examine our off-line documentation to see whether our low-context style is getting in the way of good communication. The slippery slope of low-context communication starts with telling users they must type their first name in an empty text box that is labeled First name and ends up with us telling people not to knock pedestrians down with their cars.

• “Writing in sentence fragments could cause problems for translators unless they are also working in context.”

    

  Interesting point, Matthew. I need to think about this some more, but my first reaction is that too much translation happens out of context. As a former translator, in Arabic, for the Army Security Agency, I was taught that translators do more than switch words in language A for words in language B. Investigating context is part of the job. With today’s emphasis on machine translation, I see that changing, and I must accommodate the economics of global markets. 

6 more annotations...

• WAVE5.0 is likely to be almost a complete rewrite, a process which we expect to take about a year to complete. With any luck, we’ll have a public beta to show off late this fall, with an official release in early 2011. Of course, all this is just an estimate at this point, but we’ll post updates here if there are any major changes to the timeline.
• WAVE5 also includes an ambitious project to increase the size and utility of our internal documentation by an order of magnitude (at least). We are preparing a dedicated help page for every WAVE icon or rule, detailing it’s purpose and algorithm and providing suggestions for fixing any problems it may have found. Additionally, we plan to have a longer WAVE tutorial for new and advanced users, and documents mapping WAVE’s rules and icons to common accessibility standards and guidelines. The application interface will allow for easy reference of an icon found in a report to the corresponding documentation.
• Usability tries to optimise for the majority. Techniques such as usability testing (with a representative sample) are oriented around getting the best results for the least expense. The changes to the interface based on usability testing should be kept simple and consistent for the majority of people.

• Accessibility overlaps a lot with usability, and historically web-standards + usability = accessibility.

   

  However, there can be a few things missing, such as alt-text and making sure the keyboard focus is visible. These don’t get noticed by the majority of people, but are needed for people with particular requirements.

   

  During the creation of HTML5 there have been several arguments around what is needed for accessibility, such as whether to make alt text required, and whether table headers are needed.

   

  I completely understand that it’s very difficult to create an understandable, cohesive spec for HTML, so everything possible has to be done to minimise the complexity. However, accessibility is something that has to be included in such as way that developers and authors can create all their content in a way that is accessible.

   

  For example, although complex tables are rare, it is necessary that they can be created in a way that works for everyone. Otherwise Governments and Financial institutions that have to publish content accessibly will have to go elsewhere. (Such as PDF.)

   

  Jeremy Keith summed this up well in 2007:

   

  I am more than a little concerned at the way that studying existing behaviour is being held up as a make-or-break point in discussions around HTML5… By their very nature, accessibility concerns are not going to affect the majority of users.

   

  So yes, it’s useful to pave the cowpaths when you know the common ground, but sometimes you also add another path for those that need it.

• There are several reasons why WAI-ARIAis needed:

   
   
  • It bridges a gap highlighted by modern web apps.
   
  • It can be added now without causing compatibility issues.
   
  • It can be added at a function level (e.g. to GWT and JavaScript libraries).
   
   

  There is another important reason though: It should help simplify the HTML5 spec.

3 more annotations...