Tag: Technical Writing

Posted on by

How to Write Error Log Messages

error-log-messages-how-to-write

You know in Star Trek, when they’re looking into the Captain’s Log? I bet they also had an Error Message log for when things went real bad. You know, like when the Klingons actually won and took over the Enterprise.

Ok, so what’s this got to do with tech docs?

Well, it’s a roundabout way to look at error log messages. They don’t get much love, do they?

If you’re not happy with the quality of your error log messages, see if this helps.

How to Write Error Log Messages

Severity Levels

Error messages fall into the following categories: Error, Warning, or Information.

Define your log messages according to their severity.

  • Error – The error is severe. Immediate action should be taken to avoid the loss or corruption of data.
  • Warning – Action should be taken at some stage to prevent a severe error occurring in the future.
  • Info – An informative message, usually describing server activity. No action is necessary.

Checklist using Cause/Solution Format

Use a cause/solution format when writing the error log messages:

For example:

9968: No port defined for import.

Cause:

The server cannot detect a port.

Solution:

Contact Technical Support.

9969: Bulk import not supported.

Cause:

The server will not accept an import.

Solution:

Contact Technical Support.

9807: Ignoring large value for new_attribute_name.

Cause:

The value of the configuration attribute is invalid.

Solution:

Change the value of the configuration attribute. Refer to the Help files for the acceptable value range.

Checklist for Complex Issues

In some cases, you may want to provide more background details and list the steps to resolve the issue.

6696: Source Not Available

Description:

A Source is not available. Last monitoring query showed source is unavailable.

Cause:

The error occurred because of any of the following reasons:

  • Data source is offline
  • Data source is not responding
  • Network issue

Solution:

Do any of the following:

  • Bring source back up
  • Fix network issue
  • Bring source down.

… stay tuned for next week’s episode!

Posted on by

Configuration Guides: How To Document Parameters

Configuration-Guides-how-To-Document-Parameters

So, you want to document the parameters for your new Configuration Management Guide.

Where do you start?

Here’s a checklist of what you need to capture when documenting parameters in technical documentation:

Parameter Name

Specify the name of the parameter with consideration to case sensitive naming conventions. Likewise, use the correct format and styling when entering parameters to your documents.

configuration-management-plan-template

Download the Configuration Guide Template here.

 

Location

Specify where in the configuration file that parameter is located. For example, is it part of a specific parameter set or a section of common parameter setting?

For example: This table describes the Log parameters of the Common section:

In this case, the Log parameters are part of a common set of parameters used by the service, server, or application.

Purpose

Describe the benefit to the user when this parameter is configured. Outline what it enables them to achieve and, if necessary, any downstream impacts. For example, if you turn on this option, other options are made unavailable.

However, make sure you provide enough information for the user to understand the parameter’s purpose and also how this impacts other parts of the system, for example:

Defines a locally stored backup license file. This provides protection against interruptions occurring if the connection to the license server is lost.

Prerequisites

Describe if this parameters activities are impacted by other parameter settings, for example:

Defines if a new log file is created at the time specified by the Time parameter or when the current log file reaches the size specified by the Size parameter.

A second example is if the settings are enabled if another setting is set to a specific setting in a different parameter, for example:

Defines if messages are filtered according to the Filters parameter if the Verbosity level is set to comm.

Options

Describe the parameter options is the settings are turned on or off. For example, state which options are available and then describe the settings.

  • True – describe what occurs if the True setting is selected, for example, enables statistics support.
  • False – describe what occurs if the False setting is selected, for example, disable statistics support.

Default value

Some parameters come with a default value, for example, 0, 1, Yes or No. Specify the default value so it’s clear to the reader if they need to change the setting or leave it in its default status.

Use the following phrasing: This is the default value.

Impact

Highlight if this setting impacts other parts of the system, for example, it overrides another parameter’s settings, disables another feature, or impacts the performance of the system.

Related documentation

If necessary, direct the reader to other sources of information which may help them understand the parameter a little better. For example, if it impacts another module or system.

Mandatory

State if the parameter is mandatory.

Note – identify any recommended settings or values which must be set for the parameter to function correctly, for example:

The value of the parameter must match the value specified for the Metrics parameter.

Minimum Settings

A second example is if the parameter must be set to a specific setting, for example:

The value of the parameter must be equal or greater than the value of the TimePeriod parameter.

Multiple values

For some parameters, you can specify a default value, for example, 1000 but also highlight other possible settings, for example:

The default value is 1000. The following values can also be defined:

  • 0 — no data is sent to the server.
  • 1 — data is sent to the server as soon as it is collected. This value reduces performance.

How to document parameters

Describe the parameter settings as follows:

The first sentence describes the purpose of the parameter in a single sentence.

The second sentence describes the available options and highlights the default settings, for example:

The following options are available:

  • True — enables statistics support
  • False — disables statistics support. This is the default value.

State if the parameter is mandatory. Use the following phrasing:

This is a mandatory parameter.

Summary

The skill in documenting parameters in technical documentation is to describe both the parameter and how it affects other settings, modules, or applications.

This means, as a technical writer, you need to understand how it connects to other parts of the system.

Without this knowledge, your documentation may be adequate but not help the reader understand its impact on other products.

PS – Download the Configuration Guide Template here.

Posted on by

How to find technical writing work using Quora

Are you using Quora to find technical writing work?

Maybe you’ve never heard of Quora.

Here’s how it works.

Think of it as a deluxe ‘Question and Answer’ site focused on the business community.

A lot of influential people are there. It has almost no spam or nasty comments.

If you want to develop your business, Quora is an effective way to demonstrate your expertise and generate leads.

Like the X-Factor, it uses a voting system. The better your answer, the more votes it gets, the higher it ranks, the more links you get, and the more…

Tip – You can link out to other articles, which is what I often (though not always) do.

Here’s my answer to: How can I become a better writer.

On your Quora groups

Let’s look at how to establish yourself (your personal brand) on Quora

Join 10 groups. Make sure they complement your business goals.

Avoid distractions. More than 10 and you lose focus.

Ignore groups with low engagement.

Aim to be a top contributor on your Quora group. To do this, write the longest article you can. Twice as long as others in the group. Even if your article isn’t great, people tend to upvote long posts. I think they appreciate the effort. It looks epic!

Study discussions that have the most comments. See what makes the top post stand out. Make notes.

Write a Quora post about this. Write a Quora post that deliberately takes the opposite point of view. The contrarian angle often works as it evokes a response in others and they feel compelled to respond.

Where possible, include others by recommending their sites, books, or other works. Connecting with others (especially those who have a larger network) raises your profile and gets you on their radar.

When answering questions:

  1. Be selective. Answer one question a night.
  2. Provide more detail than anyone else.
  3. Use the inverted pyramid style when writing.
  4. Use lots of white space, short sentences, and bullet lists. Write to be scanned.
  5. Link to sites you recommend but not affiliates.
  6. Format and style your answer to stand out. Don’t just copy and paste from MS Word.
  7. Add images, slides, and videos.
  8. Aim to write the standout article.

On your Quora profile page

Use a nice, professional headshot.

Write the bio in a conversational style. Talk about how you’ve helped others in the past and look forward to helping others. Be open. Encourage the reader to learn more about you.

Don’t link to your blog homepage.

Instead, link to your About page. That’s where they can learn more about you. Include an email subscription form on your About page in two places, in the side bar and at the end of the page.

On your Quora blog page

You can create your own blog page on Quora. One of mine is at klariti.quora.com

Use this to repurpose content from your blog. I usually sprinkle in a few hundred new words to tailor it to the Quora readers.

Write original content related to the questions you’re answering.

Write ‘original’ content using the material from the question you answered. Avoid copy and pasting. Instead, write a short intro paragraph to put it in context, then a summary to wrap it up.

  • Write frequently. This helps develop your voice.
  • Watch this video on how to create a writing framework.
  • Find an interesting angle.
  • Write 10 x 250 word articles.
  • Don’t write about fads, Apple, Seth Godin… the usual.
  • Focus on potential customers: how can you help them save and make money.
  • Connect it to what you do as a technical writer.

Your Quora to do list

  • Study Quora.
  • Get the app.
  • Observe how others use it.
  • Scan posts during the day. Get a feel for what works.
  • Your aim is to build credibility.
  • Write exceptional answers that make you stand out.

Summary

Before you start. Have your LinkedIn profile, blog, and business web site ready.

When they arrive, offer them ebooks, reports, or checklists. Don’t let them leave empty handed.

If you can persuade them to join your email newsletter, even better.

More next week.

Posted on by

Technical Documents: 3 Ways to Improve Quality

Who do you write for? This is a problem for many technical writers, especially if you don’t get to meet or interact with your readers. Essentially, you’re writing in the dark. But, that doesn’t mean you can’t improve the usefulness of the documents. Far from it.
Lovehearts Springtime in Beijing, China

Technical Documents: How to be more accurate

For example, you can work on improving the accuracy of the document in the following three ways.

  1. Provide Context – have you provided enough background information for the reader to understand the concept you’re about to describe? Context provides direction. Think of signposts on a map. Give sufficient information so that the reader can find their bearings and know where this piece of information fits into the bigger picture.
  2. Remove Ambiguity – check if each phrase, term, and defintion is clearly explained. In addition, clarify any points, for example, a type of network setting, that for you is obvious, but for the reader needs to be clarified.
  3. Complete – make sure that you’ve included all items that need to be explained. It’s easy to overlook one item if you’ve focussed too heavily on another area. For example, if the focus during peer reviews was on specific parameter settings, you may have overlooked the database table settings.

These are three ways to get started. What else would you add?

Posted on by — 4 Comments

How To Get More Traffic To Your Technical Writing Blog

To quote Van Halen, ‘everybody wants some.’ And what you want is traffic. Why write a blog if no-one visits, right? I have 17 technical writers’ blogs in my Google Reader & RSS feeds. Most are fine but… if they used some of the following tactics, they’d get more traffic, comments, money and Nobel prizes. Well, three out of four, anyway.

How To Get More Traffic To Your Technical Writing Blog

Apply five of these tactics and your traffic will double. No kidding, it will!

How To Get More Traffic #1: Add Your Photos

Look at your favorite technical writing blogs. How many faces do you see? Why are they all hiding? I dunno. Stick your mugshot on the page so we can see what you look like! Go on! None of us are Brad Pitt or Paris Hilton, so add a picture. Don’t be shy. People like to read about people they know. If they can’t see you…

How To Get More Traffic #2: Video

I’m no spring chicken, so if I can do it, you can. All of these video were taken on a Canon powershot.

Videos let people hear you, see your expression, feel what you’re trying to say in ways that words cannot. Making videos is easier that you think. I use Camtasia 6 for all its sins. (read my frustrated Camtasia 6 review here.)

How To Get More Traffic #3: Social Media Outposts

Use Social Media for maximum impact. With web content publishing tools like Posterous you can get the message out to all these channels with almost no effort. Posterous lets you post once, publish everywhere. Try it.

How To Get More Traffic #4: Quizzes

We all get tired of checking for split infinitives and looking for typos, so lighten things up. Add quizzes to get people involved… and try to be a little different.

  • Did you ever download software illegally?
  • What’s your manager’s most annoying habit?
  • Would you let your boss friend you on Facebook?
  • Do you know any technical writing who can reverse park? (I was going to say Women but then turned on my brain! That was so close!)
  • Do you know any men who ask for directions when lost? One for the girls, no doubt.

How To Get More Traffic #5: Comics

May not work for all sites but comics are a nice break from technical documents and other heavy reading. Why do you think they are so popular? Every serious newspaper has them, why not you?

How To Get More Traffic #6: Reviews

If they come to your site, it’s your opinion they are after. So, why don’t you give it?

#1 cardinal sin of most blogs is that they have no opinion!

Don’t be scared! I’m with you! Give your honest opinion (try not to rant or swear) and you’ll see people will respond very quickly.

#2 cardinal sin of most blogs… bland!

If your blog echoes the rest of the crowd, well, why should I come back? Stick your neck out, even a little. Some people were upset that I dissed Camtasia but y’know I’d be lying if I said it worked!

How To Get More Traffic #7: Trends

Pssst! Did you know that… everyone wants to be in the know. Keep your readers up to date. Use graphs, charts and diagrams. See Brain Solis and Information in Beautiful for inspiration.

How To Get More Traffic #8: Lists

It doesn’t have to stop at 10. Here are a few list of get started:

  • 21 Left Handed Technical Writers
  • 7 Reasons Why Adobe FrameMaker Sucks But You Still Need to Buy It
  • 12 Honest Ways to Get a Pay Rise
  • 5 Ways To Give An Honest Appraisal
  • 28 Ways to Proofred a Technical Documant
  • 1 Good Reason to Join the STC
  • 18 Mistakes Technical Writers Make Before Breakfast
  • 9 Ways to Evaluate a Help Authoring Tool

How To Get More Traffic #9: How-to guides

Ok, the technical stuff comes last. If you’re going to offer technical advice (and you should!) identify the problem, explain how to fix it, and then ask for questions or comments.

#3 cardinal sin of blogging is… blogger doesn’t interact with readers. Ask for comments. If you have a Facebook page, give them the link and connect there. Use Twitter? Create lists for technical writers and add them. Like these lists I created for technical writers and creativity.

Share, share, share!

What ya think! Fire away below.

Posted on by — 5 Comments

How Social Media Will Make You A Better Technical Writer

twitterGina Blednyh launched the Technical Communication 2.0 group in Facebook in 2009. It explores the interplay between Web 2.0 and technical communication. It’s a terrific place to exchange ideas about collaborative technologies and new approaches to delivering information.

In this interview, I ask her how Technical Writers can use Social Media and the types of content they are likely to deliver.

How Social Media Will Make You A Better Technical Writer

Ivan: Could you tell us about how you got started in technical writing?

Gina: I majored in English, but prior to that I worked for a software company. The field just seemed like an excellent fit for me.

Ivan: You’ve setup a new group for technical writers on Facebook. Could you tell us about this group? How does it differ from a BBS, for example?

Gina: Truthfully, I never participated in a BBS, though I used to lurk. For me, one of the primary differences is the openness and ease of use of a Facebook group–it’s not “just for geeks.”

Since I just began the Technical Communication 2.0 group recently, I’m not sure yet if it’s the best way to go. For example, perhaps a group on another social networking site would be more effective. But we’ve had some good discussions already and people are posting useful information.

Ivan: Brian Solis recently said that Social Media will soon become Media. It will no longer be seen as a fad. What impact will Social Media have on how technical writer work?
Gina: Wow–this is a big question! And folks far more knowledgeable than me can provide a better answer. My take is that we technical writers might need to abandon certain ideas of who participates in developing good documentation.

We might also need to expand our ideas of where technical documentation resides.  For example, a community centered around a product might include documentation, conversations between users, and feedback (positive and negative) from these users about the documentation. I don’t see this as “bad” for technical writers, however.

If a community includes both positive and negative comments and is well managed, the result can be more customer satisfaction and far better material. I don’t believe that traditional Help systems and documentation will go away entirely, though.

Ivan: What other technical writers inspire you or help give direction to the way you work?

Gina: I’ve been lucky to work with some wonderful writers and mentors! The ones who inspire me actively engage with the profession but also think about opportunities outside of it.

They embrace change and think about ways that technical communicators can better partner with other departments. Basically, they look forward and don’t waste time reminiscing about how things were done “back in the day.”

Ivan: Looking into your crystal ball, how do you see technical writing changing in the next five years?

Gina: Oy Vey! Another big question! I do see technical communicators producing more videos. And in general, I think that we will need to embrace the “technical” part of our job titles more than ever. Offering specialized knowledge will likely be an important quality to offer employers.

Technical Communication 2.0

You can find Gina in the Technical Communication 2.0 group in Facebook. http://www.facebook.com/group.php?gid=208713908443

Your Thoughts?

What do you think? Does Social Media pose a threat to the future of technical writers or can we use it to our advantage? Share your thoughts below.

Posted on by — 2 Comments

Are Daily Rates for Technical Writers Starting To Improve?

In December, I looked at the daily rates for technical writers and others in the tech comms industry. At the time daily rates for technical writers are down to $30 per hour in some places in the Bay Area.

However, maybe things are starting to turn around. In Ireland (Euro HQ for most US IT companies) Google has announced 150 new jobs, many in technical roles.  So, is the tide starting to turn?

Articles in Tech Comms publications and on other technical writing sites suggested  that daily rates for technical writers were collapsing in the US, in particular the West coast, as more writers struggle to find roles that match their previous salaries. TECHWR-L (tech-whirl), the oldest site that I know for technical writers, highlighted the case of a technical writer who’s been in the industry for 10 years and been jog-hunting for six months.

When asked what he thought where the tech docs industry was heading, his reply was, “it’s a race to the bottom”. 12 months ago, he left a high-paying tech writing job to travel but returned six months later, and looked for work.

Daily Rates for Technical Writing in California

His only job offer had been $30 an hour. Some recruitment sites quoted $40-$60 an hour. Quite a drop!

I know that when I last worked in the states, late 90s, the rates were $40-$60 per hour, and that’s almost 10 years ago.  It’s hard to believe that now, ten years later, and factoring in inflation etc, daily rates are almost cut in half.

Salary for Technical Writing in China

Salary for technical writers in China is between 15-30k RMB per month, which is approx $2.5k.

Not great by US standards but the cost of living here is much less.

Daily Rates for Technical Writing in India

According to a tech writer in Bangalore, the going rate in India is $10-15 an hour. http://www.techwr-l.com/node/1205

Jobs Trends

Many US colleagues have seen their jobs moved to India. In Europe (Ireland and UK) they tend to go to Poland as they have excellent English skills (yes, they do!) and lower tax rates.

India now produces a steady stream of qualified tech writers who are highly motivated and keen to make the most of this opportunity.

Last year I said that,  “as someone who works in Asia, and is seeing at first hand the juggernaut that is hurdling down the motorway, the race to outsource has only started.”

In the next 10-15 years, IT jobs which can be replicated offshore/offsite to lower costs will be embraced more aggressively. US companies have little choice but to do this.

The challenge for technical writers

The question for technical writers and others in this industry is how to approach this.  One suggestion would be to setup consultancy services in places like Bangalore, Vietnam, and Poland where the talent is there but the experience is lacking. Experienced technical writers, who are willing to travel and embrace a new challenge, could do very well in these countries. Staying at home may not be an option.

What do you think?

Should technical writers consider moving to places like India? Do you see signs that the recession is over. Are there more jobs for tech writers than last year?
Fire away below and share what you think.

Posted on by

How Much Time Do Technical Writers Spend Writing?

How much time do you spend writing every week? Remember, you have 37.5 hours (I know!) for technical writing every week, but how much is actually spent writing? When I say writing I actually mean developing content, so this includes illustrations, diagrams, publishing etc – whatever goes into the final deliverable. Continue reading How Much Time Do Technical Writers Spend Writing?

Posted on by

Does your technical writing have an accent?

Maybe you don’t hear your accent, but others do. When you read their documents, does the accent come through? Continue reading Does your technical writing have an accent?

Posted on by — 4 Comments

Are technical documents a waste of time?

“Don’t worry” she said. “No one reads this stuff anyway. Just get it done.” Sounds familiar? Continue reading Are technical documents a waste of time?

Posted on by

How to Write a Target Audience Questionnaire

Creating a training plan? Before you do this, you need to step a step back and work out what your colleagues need to learn. Continue reading How to Write a Target Audience Questionnaire

Posted on by

Can Outsourcing Help Your Technical Writing Career?

Daily rates for Technical Writers
Image by Ivan Walsh via Flickr

Most technical writers see outsourcing as a real threat. But, if you look at it from another angle, it’s one huge business opportunity.

Continue reading Can Outsourcing Help Your Technical Writing Career?

Posted on by

Is a Degree In Technical Writing Worth The Effort?

tech writing degreeDo you have a degree in technical writing or technical communications? Was it worth the money? If you had a second chance, would you have chosen this or opted for another career path?

One of my younger cousins has started her degree in university in Limerick, Ireland. Not the place most of us think of as the heart of technical writing. But, for Microsoft, Google and IBM this university has provides a conveyor belt, producing freshly minted technical writers every four years. It’s one of the few universities in Europe with a specialist degree in Technical Communications. Continue reading Is a Degree In Technical Writing Worth The Effort?

Posted on by — 18 Comments

Robohelp vs Doc-to-Help? Which is best for Online Help?

Robohelp or Doc-to-Help?

My client has given me permission to use whatever tool I want to do the next batch of tech docs — and they’ll buy the software. No cost to me.

Which one should I choose?

Robohelp or Doc-to-Help

Doc-to-Help was the first help authoring tool (HAT) I used in my technical writing career. We’re talking quite a while back now. Since then Robohelp has overtaken it as the tool of choice for technical writers, especially as it’s now owned by Adobe and bundled with its Technical Communications software pack.

For Doc-to-Help

  • I feel this product is under-estimated. Other technical writers (more knowledgeable than me about HATs) recommend it.
  • Opportunity to broaden my skillsets (self-interest here and not to the client’s advantage!)
  • Rapid response from Component 1 (product owners) when I contacted them. Very helpful. Only Techsmith (esp Betsy Weber) were more helpful.

Against Doc-to-Help

  • Price is not cheap
  • Will there be enough qualified Doc-to-Help experts to take over this project when I move on?
  • Does it integrate with other technical writing apps and/or Microsoft Word?
  • Worried about lack of community support, i.e. from other technical writers, if I need help.

For Robohelp

  • Oceans of Doc-to-Help experts to take over this project
  • Part of the Adobe Tech Communication suite. Maybe get discount.
  • Arguably the industry standard
  • Plenty of tutorials online if I get stuck

Against Robohelp

  • Price
  • Concern that there is no real advantage in getting the Tech Communication suite anyway as we (i.e. the client) won’t use it once I’ve left
  • Found the user interface horrible to work with last time. Admittedly, this was four years ago but you know how these things stick.

Another alternative is Madcap Flare.

What do you think?

If you were in my shoes, what would you do?

Posted on by

Is the STC Value For Money?

STC LogoSarah O’Keefe (Scriptorium) discusses STC’s new dues structure: Dues are going up; Printed publications are no longer included in basic dues; No chapter or SIG membership are included in the basic dues.

She adds that while reaction is largely negative, she finds value from her STC membership and gives some examples and reasons to join/stay with the STC. I have to confess that I disagree her on most all points. Continue reading Is the STC Value For Money?