And sometimes it’s an excuse for us not to think. At least, not to think about how to properly describe something to folks who might not be as familiar with a technology or an area as we might be.
A friend of mine keeps reminding me (and anyone else who will listen) that every group has its own jargon, acronyms, buzzwords, and terminology. In many ways, knowledge of that language seems to convey upon the people in that group some sort of elite status. I don’t think that’s true, but a lot of people do.
Technology is no different. I always say that the world of technology is third behind the UN and the military in acronyms, but it rivals the military in jargon. And, to be honest, hearing a lot of the jargon that’s bandied about in tech circles hurts my ears and my brain. That said, we’re all guilty of using jargon — I know I am sometimes.
New York Times columnist David Pogue has put together a list of tech terms to avoid. He includes some of my (least) favourite terms including the dreaded functionality.
Are there any terms or bits of jargon that you despise? If so, why not share them by leaving a comment.
Sun’s Cool Stuff blog has yet another interesting post, which points to summary of a course on how to customize the DITA OpenToolkit. According to the post:
This paper outlines the most important processes, but it leaves out many of the details, tips, and debugging notes that were included in the course.
From outline, it looks like the customization process is a bit time consuming. But, then again, you only have to do it once. Or, at least, once in a while. I mean, how often do you make major changes to your FrameMaker or WebWorks templates and projects?
Admittedly, I’ve only toyed with DITA; I don’t know many of the little details. But the information in the course summary on template extensions looks interesting. I’m wondering if it’s as (relatively) easy as creating a customization layer in DocBook.
The other day, I came across the Apple Human Interface Guidelines, which is a document that helps guide developers to create consistent, easy to use applications that will run on Apple’s devices.
The guidelines are very detailed. Check the link above to see for yourself, or download the 28+ MB PDF version. While skimming the document, I ran into two interesting sections.
The first is titled “Involving Users in the Design Process, which states:
The best way to make sure your product meets the needs of your target audience is to expose your designs to the scrutiny of your users. Doing this during every phase of the design process can help reveal which features of your product work well and which need improvement.
When you give people an opportunity to use your product (or a prototype of it) you may uncover usability problems that you did not anticipate during your initial design phase. Finding and eliminating these problems early can save you time and money later on. Clearly identifying the needs of your users helps you create products that deliver effective solutions and are typically easier for them to learn and use. These improvements can translate into competitive advantages, increased sales, and enhanced customer satisfaction.
The second is titled “Keep Your Users in Mind“, and starts off with the following words:
In addition to the basic principles of interface design, consider the needs of your audience. Are your users more comfortable in a language other than English? Do they have special needs that might affect the way you present data to them? The following sections identify areas that might influence your design.
Admittedly, I don’t own a Mac. And I’m definitely not an Apple fanboy. That said, I’ve used and played with them sporadically over the years, though. Something that always struck me was the general consistency of the applications, and the (relative) ease of use of Mac OS. Obviously, there’s something to be learned from reading the Apple Human Interface Guidelines.
That’s the thrust of this short article by Mike Unwalla. He argues that an SME who is able to write effective documentation will be able to do the job faster than a contractor or even a staff writer. Why? The SME is intimately familiar with the ideas and concepts of the product being documented, and (obviously) with the product itself.
Unwalla adds that:
The main danger of using SMEs to write documentation is that because they are so familiar with the terminology (jargon), assumptions, and shortcuts in the subject area, they forget what it is like to be new to the subject. They make logical jumps that non-experts do not understand.
I’ve seen that happen on more than one occasion when an SME tried to write documentation. In one of those cases, the documentation wasn’t too bad. However, in all cases a variety of assumptions were made based on familiarity with the product. For someone coming in with little or no knowledge of the product those assumptions caused considerable confusion.
What are your thoughts and/or experiences in this area? Feel free to leave a comment.
If you’re in the Toronto area and you’re looking for something to do tomorrow night, come out to the STC Toronto Social Jester Pub and Grill at Yonge & St. Clair. I’ll be there and Scott may be as well (if he finishes his basement renovations in time). I’m looking forward to catching up with fellow STC members, meeting some new people, and
bitching about politics and the economy discussing what’s going on in technical communications over some wings and beer.
OpenOffice 3.0 was released yesterday to the masses, resulting in their website crashing. As of this post, their website is still down. I was able to download a copy of the Windows version (insert punchline here) and I’ll be evaluating the release over the next few weeks. The company I’m currently working for uses OpenOffice to develop technical documentation and there is some interest in migrating.
Initial reviews suggest that although the UI is still a bit clunky, the performance has significantly improved from the previous version. So, given the state of the economy, will companies increasingly choose open source applications such as OpenOffice as a way of trimming the balance sheet?