Why Good Technical Writing is Good Marketing

June 8th, 2006

We’ve all experienced the manual from hell.

You might have in your hands the greatest piece of software, the most fetishistic piece of hardware, or maybe just a kid’s toy with “some assembly required”.

But the experience is ruined because the manual makes no sense.

Is there an excuse? No, there’s not.

There was a time when manuals had to be written up on typewriters or longhand, they had to be sent to a typesetter, professional illustrators were brought in, proofing and correction cycles were long and painful… but the job got done.

Now it’s easy. Digital cameras, Technical illustration in PhotoShop, 3D rendering from CAD, great page layout tools like Adobe InDesign, Acrobat PDFs, for proofing and electronic distribution, printing plants worldwide that can take PDFs and produce manuals locally… Even translation is easier than it has ever been.

The problem is most acute in small and medium-sized manufacturing firms. To maintain full-time staff to deal with these things is often a substantial financial burden. Many such firms actually develop their products in countries other than their end markets… so the engineers don’t even speak or write the language of the end customer, or don’t do so natively.

With the web, you’d think there would be an ongoing dialogue between manufacturer and user. Sure, many companies post their support phone numbers, but few actually provide ongoing guidance online, and many that do, do so inadequately. The long wait for support with most companies is a pretty good indicator that they are spending in support what they didn’t spend in documentation.

So why is it still a last minute effort by a low ranking engineer with no grammar skills and a complete unwillingness to use spell check? Why is there no user-testing? Why do the online help, the print manual, and the PDF on the provided CD all have inconsistent, often contradictory, always incomplete information?

The answer may differ between organizations, but it really comes down to a lack of commitment to end users. Many organizations isolate themselves from their users, putting the burden on retailers or their support staff, after the sale. There’s a booming aftermarket for manuals and magazines for most software products. All are indicators of a failure to communicate.

If you recognize this problem in your organization and would like help resolving it, contact me.

Posted in Information Architecture, Technical Writing | No Comments »

Back to Information Architecture

December 26th, 2005

This guy’s doing some cool things: EcoLanguage

These animated diagrams are great to visually show how economics works. He should switch to Flash, so the images are clearer, and larger, without the download time. And a professional voice-over would be good. But this is by far the clearest way to explain economics.

And people need to understand economics, badly.

This is Information Architecture approaching it’s highest potential.

Posted in Information Architecture | No Comments »

The Secret Value of Business Blogging

December 16th, 2005

Those who followed the meteoric rise in the number of websites in the ’90s will
see parallels in the similarly stellar growth of blogs. By some estimates, the number of blogs doubles every five months, and is approaching 15 million blogs worldwide — Which makes blogging the buzz, everywhere you go. But most people are still at the stage of asking: “What is a blog” and “Why should I care?”. Businesspeople often ask, “How can I use a blog to help my business?”

What is a Blog?
The word “blog” is a contraction of “web log”. Like an ordinary website, it has text and navigation that uses HTML to display content in a web browser. It differs from an ordinary website by using specialized software to manage the content in a particular way. This blog software resides on a web server. It allows the user to write articles and manage images and links within the web browser itself, with little knowledge of HTML, and no special tools required.

When you write an article (called a “post”) for your blog, the post appears immediately online, on the blog’s home page. The most recent article is always at the top, and the rest in descending chronological order. As new articles appear at the top, older articles “roll off” the home page. Each article is also stored in an archive, where writings continue to be available for as long as the blog exists. Links to the archives are automatically created and managed by the blog software.

The Secret Value of a Business Blog
Because it is easy to write a post, and the posts appear chronologically, it forms a journal. For a business, a blog is a great way to keep customers, employees, vendors, and the press up to date on company or industry news. But the secret value of blogs is not just how people read them, but how search engines, like Google, read them. Blogs are magic at Search Engine Optimization (SEO).

The secret is that, over time, posts written about a particular product, service, or industry will create a cumulative volume of pages that are rich in keywords related to your specialty. The more you write, and the more careful you are about embedding keywords in your posts, the higher your blog will appear in search results.

To really power your way to the top of the search engines requires getting more sites to link to yours. Google uses the number of links into your site to establish a “page rank”. Page rank, plus keyword matching, are combined to position your page in the search results. But to really drive traffic to your blog, you need to become an “active blogger.”

Passive Bloggers Write, Active Bloggers Link
If you just write articles on your blog, you’ll eventually get more people viewing it. But this is the passive approach. To crank it up, become an active blogger.

Blogs have the ability to accept “comments” from readers. Sometimes this feature is turned off to avoid “comment spam”, but most sites still accept comments. After you write an article on your site, go to like-minded blogs, and use their comments to notify them of your article. These comments normally link back to your site. Typically, active bloggers watch their comments. Most are looking for good material for their own blogs, So they might follow up on your comment by mentioning your article on their blog, and linking to it. Over time, this increases the number of pages linking into your blog, and your search engine positioning will magically rise closer to the top.

Ping the Blog Search Engines
Traditional search engines only update their links every few months. This is inadequate for blogs that are updated weekly, daily, even hourly. So specialty search tools for blogs have stepped in to fill the gap. These tools allow you to “ping” them each time you post a new article. The ping notifies them so they can immediately update their index of blog entries. Blog search engines just store an entry of each post, and link directly to the archive of that post. The archive has a permanent address (called a “Permalink”) so that, even years in the future, a search will return the correct results.

If you start a business blog, post at least two articles per week, and keep at it, and it will pay dividends. If you become an active blogger, you will soon create a network of links and relationships with other blogs that will increase your authority both to readers and to search engines. Becoming an authority in your field can only help your business.

Blogging tools:
WordPress
Blogger
TypePad
Moveable Type

Blog Search Engines:
Googles Blog Search
Technorati
BlogPulse

Sources of Business Blogging Information:
Author’s Blog
Blog Herald
The Intuitive Life
Wikipedia on Blogs

Posted in Information Architecture, Site Design | No Comments »

Requisite Entry on Katrina

November 26th, 2005

I really don’t feel much like writing today, but I’m watching c-span, news reports, etc. and feel like I have to mark my thoughts.

All energy, after an event like this, should go to saving lives and finding solutions.

But It is obvious that there was warning both of the geographic problems of New Orleans, and of the severity of the storm.

It is obvious that the response mechanism waited for the aftermath to begin, rather than being anticipated from the point the storm was identified as both large, and headed for the LA coast. That was a terrible mistake. We had enough warning to have water, food, and rescue vehicles at ready. We had enough time to have law enforcement ready. This is a clear case of mismanagement.

But now, give blood, give money. Give it to the Red Cross. They know what to do, how to do it, and they do it all the time. Thank you, people of the Red Cross.

70% of the citizens of New Orleans and the surrounding area are black. The people who stayed behind were disproportionately black. Don’t draw conclusions about the problems of the looting, shooting, rape — or for that matter, the slow response — being race-related. If there is a problem, it is more the long-term problem of poor states getting poor service from a political system that is of, by, and for the wealthy.

I believe the best efforts are now being directed to the area, and the private sector will make up for the weak Federal and State response going forward. It’s a big mess, and people have just started to suffer from it. It will cause economic and social ripples for a decade.

The weak response is based on several things: the lack of fact-based decision-making that is the hallmark of Republican leadership, the simple cost-benefit problems of raising a city above sea level, the nature of poor people under extreme pressure, the obsession with “homeland security” at the cost of actual homeland security, the informational isolation of the Bushies, the primary interest of the Feds of being on camera, looking “in-charge” vs. their willingness to actually do the work of being in charge.

Don’t take my word for it, here are the details. Quick quote from the end of the article: “But with the change of administration in 2001, many of Witt’s prevention programs were reduced or cut entirely. After Sept. 11, former FEMA officials and outside authorities said, Washington’s attention turned to terrorism to the exclusion of almost anything else.”

On another note, in my area of Northern California, regular flooding of the valley towns of Marysville, Yuba City, and Sacramento led to these towns being periodically buried in mud. This led to the end of Hydraulic Mining, but regardless of the debris from Hydraulic Mining, this problem would have occurred anyway. The Sacramento Valley floor with its rich soil for farming formed this way, before we were here to see it.

To resolve the annual destruction the flooding brought, the cities were raised. It was done with true horsepower and people power.

Retaining walls were built in front of the buildings with walkways remaining on then-ground-floor levels, and dirt was brought in and dumped between the retaining walls, raising the level of the streets.

Once this was completed, the downstairs merchants moved upstairs and new entryways were completed. The downstairs became basements. Walkways at street (second floor) levels were built that became roofs over the old walkways. Glass bricks were embedded in the new sidewalks to light the still-used passageways beneath.

And levees were built. They’re in rough shape now, and have failed a number of times, creating problems in small towns.

But Sacramento so far has been spared.

Our good congressmen (recently deceased) Bob Matsui fought for improved levees for years. Our bad congressman John Doolittle fought against them… preferring instead the Auburn Dam. I won’t go into the foolishness of THAT. Finally, an agreement was reached, and levees will be improved. Planning ahead is a good thing. Of course, we were lucky. The perfect storm hasn’t hit.

Will they be improved on time, and will the improvements be adequate, when the perfect storm finally does hit? Can we use the old adage “Time will tell” or should we jump to it?

On thing we can do is kick Doolittle out on his ass… And put in someone with some foresight. Matsui was an awesome Senator… hard to find any way to criticize him (imagine that!). His wife, Doris Matsui has taken his position. Let’s hope she’s as effective.

I bet the people stranded on the Gulf Coast didn’t think politics effected them personally. Now, I hope they know better. Now, maybe we all know better, and won’t trust Republicans with our lives, any more. I can wish, can’t I?

Posted in Information Architecture, Politics | No Comments »

What businesses can learn from the Katrina debacle

November 26th, 2005

There’s a lot out there about crisis response for businesses. Much of this applies to what happened on the Gulf Coast. A lot can be inferred. Obviously larger companies can do more of this stuff than tiny companies. But tiny companies are usually in one place, and just are in survival mode after such a crisis. I’m also going to note the governmental failure to follow these principles:

1) Send the company CEO or president to as near the location of the incident as possible, as soon as possible. Immediately announce his/her intent to do so, if they can’t go immediately due to local conditions. Bush should have helicoptered in as soon as the rain stopped. He didn’t have to stay long.

2) Start with your people, money can be dealt with later. Take care of people. Basic needs. The people who were in the dome needed water, food, sanitation and healthcare. They were told to go there, and many arrived before the storm got intense. Yet there was no thought to what it would be like 3 days later. And during those days, no one was queued up to bring in supplies and transportation and law enforcement immediately after the storm cleared.

3) Figure out what you can do for your community. What resources and people power can you put to work to help people? Customer service and billing should immediately distribute statements of policy to customer-facing people that the company will work with effected customers, and no late fees, account closures, etc. will occur for those in effected areas. Accept vouchers from FEMA, Red Cross, etc. even if you’re not sure you’ll get compensated later.

3) IT matters. Recover PC hardware if possible, ignore the rest. Hard drives are enough. People who can work will need their PCs. But make it clear: people are what matter; real estate, insurance, etc. are secondary. Make sure that those you ask to work under these conditions are OK. Most will be relieved to hand over most responsibility and deal with their own issues, but will feel some guilt. So keep them in the loop.

4) Be prepared: multiple redundant data centers, digital infrastructure that is hosted, rather than local, etc. will all go a long way to keeping things moving under these crisis conditions. It is really stupid to host your website on an internal server. Hosting centers are built with security, power redundancy, and emergency plans that your company probably can’t do as well.

5) But mostly, cross training and management teams that are not spread too thin… lean budgets may seem like a great idea to provide the most benefit to shareholders… right up until a chunk of your company is under water, and “the only guy who knows how to…” is missing, or injured, or traumatized. This goes to company culture, too. Companies that collaborate can adapt under extreme circumstances, while those that rely entirely on internal competition to drive performance fall apart. This is due to information and power hoarding.

6) Use a blog. Post often. Internal and external blogs are great. Employees need to know, just as the public does. Have a great writer tag along with the boss, and go to it. Make sure the posts genuine and useful and about the Boss’s observations. He can take notes and the blogger can expand, but it’s better if the boss writes (quickly) and the blogger cleans it up. Under stress, the boss could say the wrong thing or write things that cause confusion. The blogger should have a frank relationship with the boss.

7) Make sure your organization has (at each office) a satellite phone and a laptop that can use the phone as a modem. Cell phones probably won’t work. Consider a wireless network. A local wireless network can be set up quickly. You’ll need inverters, batteries, even a solar panel or two would be good. You’ll be worse than useless if you go into an area and can’t communicate after the batteries go dead. Have battery powered lights, and radios stored for these occasions. Of course, first aid kits are already done, right?

If I come across more, I’ll add them to this article.

Posted in Information Architecture | No Comments »

« Older Entries
Newer Entries »