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.
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.
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.
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:
Be selective. Answer one question a night.
Provide more detail than anyone else.
Use the inverted pyramid style when writing.
Use lots of white space, short sentences, and bullet lists. Write to be scanned.
Link to sites you recommend but not affiliates.
Format and style your answer to stand out. Don’t just copy and paste from MS Word.
Add images, slides, and videos.
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.
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.
Technical Documents: How to be more accurate
For example, you can work on improving the accuracy of the document in the following three ways.
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.
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.
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?
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.
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.
Gina 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
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?
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.
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.
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?
Do 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?
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.
Sarah 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?
