Palimpsest
Wednesday, March 19, 2008
 
WritersUA: Pundits panel
posted by Sarah
 The pundits' panel is always fun and usually slightly wacky. The panel this year was Alan Houser (Group Wellesley), Scott DeLoach (ClickStart), Bogo Vatovec (Bovacon), and Kevin Siegel (Icon Logic).

Tools and technologies

Alan Houser: XML-based authoring and publishing will remain a niche component among user assistance workflows. Alan points out that XML-based tools do not match the features of conventional authoring tools and haven't achieved substantial market share. Thus, he expects that this will remain a niche approach.

[I would have to disagree strongly with this. Organizations are implementing XML despite the challenges with the authoring tools. As the tools improve (and they HAVE TO because surely it can't get a whole lot worse), they will become less of an obstacle and thus open up XML-based authoring to more people. In our business, we are seeing demand for XML-based authoring across every possible industry, company size, and content type.]

Kevin Siegel: Adobe will develop the Tech Comm Suite for the Mac

[Sorry, Kevin, I suspect this is wishful thinking. I'll be happy if you're right, though.]

Bogo Vatovec: User assistance technologies need to bridge the gap between readers and creators and support user-generated content.

[Is this a prediction? It seems like more of a feature request. But I would have to agree that this is needed and will probably happen.]

Aha. The tools aren't so great and it's the help authors fault because we're asking for the wrong features.

Scott DeLoach: Within seven years, your applications, your files, and almost everything else will be web-based. (And also, PCs, phones, cameras, and GPS systems will converge.)

[Yes. This is already happening with GPS-enabled phones and the like. I'm not too sure about the seven-year estimate, but the convergence assumption seems reasonable. And the move to the web is clearly already underway.]

Scott thinks that we won't have RoboHelp for the Mac, but that RH will run on the Mac because it will be web-based!

Joe Welinske thanks Scott for "going out on the edge there" with a prediction that "in seven years, gadgets will be smaller." Hee.

User Assistance

SDL: Within five years, all software UA will be embedded or web based. Web-based content means only one copy and updates are immediate. Other web-based UA will become part of the help -- wikis, discussion groups, FAQs, and the like.

[That seems uncontroversial. Next?]

KS: Unsociable help systems won't be invited to the party. Today's students want to be fully engaged by media and games. He predicts the era of "rich media." If your help system isn't dominated by interactive commenting and interactive media, it will be irrelevant.

[This may be true for tools that are optional (think Quicken), but not so much for tools that are needed to do your job (not optional).]

BV: Introverted technical writers will not be writing help any more and will be replaced with experts moderating support forums. Companies should focus on enabling search of user forums rather than on help development. Technical writers can no longer afford to hide in their cubes, they must go out and become experts and talk to the users. At this point, they are support engineers rather than technical writers.

[Second reference today to "not providing obvious information" and instead focusing on important information.]

AH: Rich Internet Application technology will fill the current void in help delivery engines.

Lots of stagnation in the help delivery tools and mechanisms, but more innovation in the last year. The logjam seems to be breaking with the new RIA technologies, such as Adobe AIR.

[Totally agree with this.]

Joe: "The majority of the help created in the last 20 or 30 years is pure crap because it was created by people who would much rather be doing anything else." But the people in this room are creating much better stuff, he says.

Bogo definitely struck a nerve with his comment about not being introverted. Several comments about how introverts can TOO do this job.


IT Industry

SDL: Within 10 years, the web will not be free. Access devices and access will be free or inexpensive. Free web access will include ads on pages and ads at set intervals.

[Interestingly, that's exactly the model that the "free municipal WiFi" in Portland uses. You can access the web for free, but you get a sidebar full of ads, and an occasional interstitial ad (interspersed when you try to follow a new link).

I hope he's wrong about this one, but I've got a bad feeling that he's probably right.]

KS: Smaller training companies could virtually meet their demise. Companies must add virtual classes and eLearning. This puts the responsibility for the software on the student instead of the training company. The technology works, the bandwidth is available, and the cost of hosting online meetings is reasonable.

[We are offering a significant number of classes online, and I suspect that this is true. Although classroom learning is better than web-based instruction, it's also a lot more expensive. So, web-based training provides a cost-effective alternative and removes a lot of the friction associated with travel required for classroom learning.]

AH: The quality of machine translation will improve dramatically within 5 years and will match the quality of human translators within 10 yeras.

[Oh, not a chance. (Usually, I agree with Alan on stuff. Not today.) However, it may be that machine translation will become "good enough." Hand-crafted translation may be reserved for high-impact documents rather than for "utility" documents.]

BV: Computers as we know them will disappear. We will have one-for-all devices, specialized devices, and embedded computers. Additionally, the oddest devices, like kitchen ovens, have full computers embedded. So the challenge is to figure out how to provide user assistance for the oven?

Bogo thinks that we will not "pay for access to the Internet" as Scott said, but instead that we will "pay to get non-crappy content."

Fun panel to round out a great conference!

Labels: ,


7:51 PM Permalink | |
 
WritersUA: DITA pilot techniques
posted by Sarah
 Mark Wallis of IBM ISS on how to run a successful DITA pilot. Some great information in this presentation on how to reduce risks.

He recommends selecting your pilot project based on the following items:
They had one person out of a group of twelve, a "senior in name only" writer, leave because of this transition.

The ideal team for a pilot will need cross-functional and complementary skills:
Some advice on planning your content. (And it's worth noting here that these apply to good writing and topic-oriented content rather than to DITA tools.)
Some interesting discussion of "task support clusters," which include conceptual overviews, related tasks, deep concept, and reference information. (Michael Hughes did a presentation on this earlier today, which I unfortunately was not able to attend.)

They set up a DITA War Room in a small conference room and met at least daily (1.5 to 2 hours per day. Yikes). They set weekly goals and used small tasks to build momentum.

There was also heavy use of an internal wiki to put up initial "straw man" design, then revise, comment, and discuss.

Layering deliverables
Implementation deliverables were split out into smaller tasks, such as:
For the third time, he points out that they are no longer documenting how to use a check box, so I guess I'll mention it.

Choosing the DITA toolset

Task Modeler (free) for building and managing ditamaps, defining relationships between topics, and creating skeleton topics (stub files).

DITA-compliant editor to edit your topics.

Compiler (part of open source toolkit). Compiler? What are they compiling? HTML Help? Oh. He just referred to Ant as a compiler. Ohhhhhkay.

Proof of concept

They picked a subset of the pilot to do the proof of concept.

The presenter's boss is quoted as saying, "There's no such thing as bad weather, only insufficient clothing." I'm guessing that she's never been to Minnesota in winter.

The objectives for the proof of concept:
They learned that deliverable formats matter because they must deliver several different formats.

Managing costs

Purchase toolsets only for pilot team.

After completing proof of concept (successfully!), invest in tools for the remaining writers.

Wiki

They used their wiki to capture conventions and guidelines.

Improving acceptance

They paid attention to the change management issues. He doesn't mention it here, but I would assume that the combination of an acquisition by IBM plus the requirement to change the authoring environment could have caused significant angst. Their approach included presentations, wiki content, email discussions, and online training.

At the point of transition, DITA boot camp was offered.

They used collaborative walkthroughs, or reviews, to help standardize their content development. Interesting. This sounds as though it could be a) threatening and b) an unbelievable time sink. But just maybe it might also c) help improve the content.

Other lessons learned

Think more, write less. (Don't document the obvious, don't document common user interface convention, write only if you're really adding value.)

Don't squander your ignorance. (If something makes you stumble in the interface, that will probably also cause problems for your users, so capture it.)

The more structured your content, the easier the transition to DITA.

Documenting the obvious teaches readers to ignore your text, so don't document the obvious.

The handouts are available here: http://www.writersua.com/ohc/suppmatl/

Labels: , , ,


5:29 PM Permalink | |
 
When not-so-related links attack
posted by Alan
 In his presentation today, Michael Hughes mentioned that writers sometimes get a little too link-happy in help. For example, we may think we're being helpful by providing a link to a topic that we see as related in the grand scheme of things. However, to a user who is focusing on a particular task that has no immediate dependency on a "related" topic, that link is unnecessary or even a distraction.

Michael's objective was to create topics that give the writer just enough information to get back on track without interrupting the task flow. Providing lots of links can get in the way of the flow. That being said, it's probably unwise to take this more minimalist approach as a license not to put in links at all. For example, links that define terms or acronyms can be crucial to understanding a task.

Labels:


3:45 PM Permalink | |
 
WritersUA: Day 3, Morning
posted by Sarah
 Dave Gash (hypertrain.com) leads off the festivities with a discussion of the UA Holy Grail. And no, it's not DITA.

He is discussing True Separation of Content, Structure, Format, and Behavior.

Interesting, because we normally hear about separation of content and presentation -- he's making finer distinctions.

According to Dave, the current authoring method is to using WYSIWYG and code editors, often in combination. And as we work, we insert what's needed wherever it's needed. The result is that documents work -- once -- but are very difficult or impossible to update, maintain, and control.

Spaghetti-code documents make our own jobs harder.

The conventional wisdom is to separate content and formatting. Content is "stuff on the page"; therefore format must be "everything that is not content."

Content could include HTML, CSS, and JavaScript. Separating out CSS still leaves "junk" in the content pages.

Dave proposes a more refined model: content, structure, formatting, and behavior.

* Content is XML
* Structure is XSLT
* Format is CSS
* Behavior is JavaScript (JS)

This will be more maintainable, which means:

* Ability to change any components without breaking the others
* Ability to reuse any component in other pages or projects
* Ability to control each component's resource allocation (that is, who creates each piece?)

How to improve your pages:

1. Identify and externalize JS behavior.

* Find the embedded scripts (<script> tags) and remove them with a reference to an external foo.js file.

<script language="javascript" src="foo.js"></script>

2. Identify JS behavior that could be CSS and convert it to CSS rules.

"If you can encode with CSS and make it declarative instead of procedural, you're way ahead of the game."

* Catch "sneaky" JavaScript behavior, such as mouseover events, that could be CSS rather than JavaScript. Event handlers that call JavaScript almost always start with "on" -- easy to identify and many can be replaced with CSS hover pseudoclasses.

.expterm:hover {font-style:italic; }
.expterm {text-decoration:none;}

Removing the code from the HTML greatly simplifies the page.

3. Identify and externalize CSS styles, recode any local formatting as classes.

Get rid of "deprecated tags and doo-doo like that."

Get rid of style attributes, font tags, b tags (become span tags).

"It's said that comments are for someone who comes behind you six months later and needs to update your code. This is not true. Comments are so that YOU can figure out six months later what you were doing in the code."

So you should comment your code.

4. Semantically mark up content as XML.

Dave's definition of semantic markup? "call things what they are."

5. Identify desired HTML output structure, write XSL transforms to produce it.

So...what's in it for me?

Discrete, maintainable, controllable components
* you can change one component without breaking others
* You can share components with other pages
* You can separate work load by skill sets
* Set it and forget it! (for everything except the content)

Code examples are available at Dave's web site: www.hypertrain.com

Questions about tools. No, he won't recommend tools. Question about schemas...Dave says the first thing that comes to mind is...DocBook???

Yikes. In an answer to a question about print and XSL-FO, somebody recommended asking....me! (I swear I didn't pay her for that, and I don't think she even knew I was in the room. Quite surreal.)

##

My only disagreement with this session is with the separation of XML as "content" and XSLT as "structure." It's my opinion that the XML includes the structure, and XSLT just gives me a way to express that structure into HTML or other formats.

I also question some of his tag names, such as <expander> for a term/definition group. The expander tag name is really a description of the desired behavior (expandable text) rather than the semantic function of the content (definition of a term). I would probably choose something like <glossaryitem> for the container, leaving opening the option of changing the behavior to something other than expansion in the future. Same quibble with <ddblock> (drop-down block).

I do like the use of the tag name for step results.

Great presentation from an energetic presenter whose motto is, "If I have to be awake, you do, too!"

Side note: I'm pretty sure that if you tied Dave's hands behind his back, he would lose his ability to speak.

Labels: , , ,


1:16 PM Permalink | |
 
Things I've learned at WritersUA that have nothing to do with technical communication
posted by Alan
 I've been in Portland with Sarah and Matt at the WritersUA conference. I've attended some informative sessions, but I have also picked up a few bits of information that I didn't learn from a conference presenter:

Labels:


10:30 AM Permalink | |
Monday, March 17, 2008
 
WritersUA: Opening Session -- Searching for the Origins of Language
posted by Sarah
 Joe Welinske is doing introductions. Attendance this year is 500, up around 100 people from last year. There are a lot of people in this ballroom.

The opening speaker is Christine Kenneally, her book is The First Word: The Search for the Origin of Language, which is nominated for an LA Times book prize.

"Humans have a miraculous ability to acquire language, but they must be spoken to in order to acquire language." If not spoken to, a human will not learn to speak.

The question she is trying to answer is "Where did language come from? How did it begin?"

Speech is ephemeral. No fossil record of speech, which makes research extremely difficult. "No verbs preserved in amber." We can look at the fossil record for the evolution of the brain, tongue, larynx, lungs, and other organs of speech.

Figuring out the origin of language is"the hardest problem in science today" Hmmm. I can think of a lot of scientific problems. And a lot of hard ones.

She goes on to describe language components and where animals have overlapped with them.

Words: Average is 60,000 words for humans. Words are a nexus of information; they provide sound, meaning, and structural possibilities. Kanzi the bonobo (chimp) understands spoken English (hundreds of words) and uses lexigrams (pictures). Rica the border collie -- knows the words for hundreds of objects
Dolphins make many sounds, including a "signature whistle," which other dolphins associate with that specific dolphin -- like a name.

Syntax: Kanzi has syntax at a human three-year-olds level. Some animals in the wild use syntax.

Ability to think/cognition: Several animals, including chimpanzees, dolphins, and elephants, have the ability to look at themselves in a mirror and understand that they are looking at themselves.
Crows make tools.
Alex the parrot speaks 50 words, 7 colors, 5 shapes, and understands the concepts of none and zero.

Gesture: Chimps gesture freely and flexibly and their gestures are instinctively familiar to humans.

Cooperation: Language requires a back-and-forth exchange.

That was all very fun, but oddly I read a National Geographic Magazine article yesterday that covered the very same animal examples. You can read it here.

This presenter needs some visuals. She is speaking and reading from her book. The book excerpts are too long. She's a good writer, and I definitely want to read the book. Myself. But the topic would seem to lend itself to visuals and there aren't any. No slides, no pictures, no nothing.

Labels:


2:11 PM Permalink | |
Thursday, February 21, 2008
 
Portland, here we come
posted by Sarah
March 16-19, you will find three of us at the WritersUA conference in Portland, Oregon. We'll be in the trade show booth and Sarah is doing a presentation and a panel.

And what does this have to do with acrobatic Peeps? We have discovered that Cirque du Soleil will be in Portland during the conference, just down the road from the conference hotel. So, we are planning to attend a performance on Monday evening (8 p.m.). If you'd like to join us, drop me an email.

Labels: ,


2:20 PM Permalink | |