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.

• Ivan: http://www.ivanwalsh.com
• Twitter: http://www.twitter.com/ivanwalsh
• Facebook: http://www.facebook.com/ivanwalsh
• Business Week http://bx.businessweek.com/profile/ivan-walsh/iwalsh905/
• And also on Disqus, Flickr, LinkedIn, Delicious and Google Reader

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.

• Adobe FrameMaker list http://twitter.com/ihearttechdocs/adobeframemaker
• Creativity list http://twitter.com/ihearttechdocs/creativity
• Technical writing software http://twitter.com/ihearttechdocs/technicalwritingsoftware

Share, share, share!

What ya think! Fire away below.

Scott, over on Words on a Page, says, “If you want to improve as a writer, you not only need to write. You need to read. Writing and reading are two sides of the same coin. You need to do both to achieve your potential.” I head downtown most weekends and buy 2 or 3 books, mostly business, history and some fiction. Every so often I run out of options (we’re in Beijing) and get something I usually wouldn’t buy, for example, Iain M Banks. Reading outside my comfort zone stretches me. I encounter writing styles, opinions, and  information that I usually side-step.

Scott adds that by reading, ‘you’re exposing yourself to different voices and viewpoints. And you can pick up some new techniques. Not only that, you get a great opportunity to see what other writers are doing well and what they’re doing badly.’ This brings me to dear ol’ Stephen King.

How Stephen King Made Me A Better Technical Writer

I’ve read Stephen King (on and off) since I was a teenager-almost 30 years. After going through Jack London, King Arthur and HG Wells, he was the first modern author that I read.

What did I like most?

The tension, crisp writing and little details that sucked you right in. You had to read on. Would Cujo eat the small child? Most of this was horror, something I grew out of after high school.

But he also wrote another book, On Writing.

If you’re interested in the mechanics of writing, get your hands on this. For me, it’s his best book — and I wish he’d go back and read it.

Why?

Because it teaches you how to write tight prose, remove the waffle, and stay focused. All the things I try to do as a technical writer.I hope he’ll turn a corner someday which is why I give him so many second chances…

What am I reading now?

I tend to mix and match. I have a stack of books next to my bed and dip in and out.

Some are:

• Groundswell, Social Media book
• Built to Last – what makes companies success over the long term
• Stephen King – Duma Key, really lame, especially after his early stuff
• Graham Greene is always a pleasure. Our Man in Havana is a favorite
• Plato’s Apology
• Genghis Khan bio, life in ancient Mongolia
• Margaret Atwood’s The Handmaid’s Tale
• Iain M Banks – pretentious drivel! I had such high hopes. Philip K Dick is the best sci-fi writer for me.
• Catch 22 – ok, bit dated
• Al Ries, Focus and the 22 Immutable Laws of Marketing
• Tom Peters, Peter Drucker and Seth Godin are all there too.

Seth’s writing style is, for me, the best out there right now, at least in the business world. Tight, crisp, and funny. No words wasted.

I rarely buy magazines anymore as most are close to 5 euro in Europe. Instead I pony with the difference and get some books.

How about you? What are you reading?

Carsten Mende explains how loan words are used in China and Japan. These are English words that are commonly used in everyday Chinese, (i.e. loaned) but may not translate correctly if taken literally. He looks at how the ‘Chinese and Japanese languages incorporate English terms and how they are used’ and gives suggestions on what to avoid when translating documentation into these languages.

Difference between English, Chinese and Japanese syllables

He starts by showing the different between how syllables are created in these languages. And as someone who has studied Chinese for a few years, it’s both fascinating and frustrating. Oranges and apples, so to speak.

Latin – allows ‘numerous variations for combining letters and the amount of syllables is extremely large. English has more than 11,000 syllables.

Chinese and Japanese is very different: Chinese (Mandarin) is written in characters; each reflects a syllable and not a single letter.

Adopting loan words in Chinese and Japanese

He shows three mechanisms for the adaptation of English words in both languages:

• Phonemic way
• Semantic way
• Adaptation without any transformation

For example: Coffee 咖啡 ka fei

Suggestions

He cautions that when translating or transferring into a foreign language, ‘even obvious things may shape up as something completely different. So you should always treat your customer attentively, take him seriously and be prepared to communicate in his mother tongue.’

Read Carsten Mende here

Opportunities

The quality of technical documentation in China is often very poor. It’s not for lack of trying, rather they lack experience technical writers and have had little exposure to international audiences.

For foreigners this represents a huge opportunity. Technical writers who can come to China and test the waters could do very well. The pay is increasing all the time and the cost of living significantly lower than elsewhere.

Fancy moving?

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

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.

It’s not the questions you ask that matters, it’s the way you ask them. Technical writers, business analysts, and developers all ask questions. They want answers. And some are better than others. Some ask many times to get the definitive answers. Others think they have the answer but, on closer inspection, have overlooked some vital point. So, how do you ask the right questions?

How to Run Structured Interviews & Improve Task Analysis

When working on business transformation and outsourcing projects, I’d spend endless hours interviewing people.

The more I did it, the more mistakes I saw in my interviewing techniques.

I wasn’t getting the answers I wanted. I was losing time and getting bogged down with thorny SMEs. My manager suggested I look at Structured Interview techniques.

• Structured Interviews are a quantitative research method commonly employed in survey research. It helps ensure that each interview is presented with exactly the same questions in the same order. We used it for Process Design work and developing Action Plans.
• Answers can be reliably aggregated and comparisons made with confidence between sample subgroups or between different survey periods.
• Structured interviews allow you to collect data for a statistical survey, for example, data can be collected by an interviewer rather than through a self-administered questionnaire.
• Standardizes the order in which questions are asked of survey respondents, so the questions are always answered within the same context.
• Minimizes the impact of context effects, where the answers given to a survey question can depend on the nature of preceding questions.
• Used as a qualitative research methodology. These types of interviews suit focus group studies in which it helps to compare/contrast participant responses in order to answer a research question.
• For structured qualitative interviews, interviewers develop an interview schedule which lists the wording and sequencing of questions.

Later, I organized workshops on Structured Interviews where we showed Business Analysts how to interview SMEs and glean the information they needed.

How To Ask Questions for Technical Documentation

Tom Johnson also discusses how to ask questions, for example, to define the topics for an application, ‘Regardless of how many topics you decide to include in your help, asking questions is a tool that can serve you well in all areas of life.’ http://www.idratherbewriting.com/2010/02/17/the-art-of-asking-questions/

How To Ask Questions

Some things to consider are:

• When to ask Open v Closed questions, i.e. which is the most appropriate.
• How to interview groups, i.e. how to ensure that quieter types get heard and not bullied/intimidated at workshops and
• How to verify what the person said is what they actually meant to say..

The final one is much more difficult than you’d think.

How do you interview people?

What mistakes do technical writers make when interviewing? Do they ask too many questions? Or assume they have the information? How do you cope with difficult people at interviews?

This week I speak with Svi Ben-Elya, one of Israel’s first technical writers.  After moving to Israel in the early 1980s, Mr. Ben-Elya developed a reputation for helping companies solve their documentation problems innovatively but painlessly, while within the technical writing community he became known for helping others. Mr. Ben-Elya’s reputation enabled him bring together all parts of Israel’s technical writing community (independent contractors, technical writing companies, and in-house writers) in Oct. 2003 to found Elephant. http://elephant.org.il.

Svi Ben-Elya on Technical Writing & Professional Empowerment in Israel

Ivan: Could you tell us a little about Elephant?

Svi: Elephant is a growing community of Israeli technical writers and similar professionals that benefit from helping each other. It began as a small networking group of very experienced technical writers who were either out of work, underemployed or in fear for their jobs at the height of the last hi-tech recession. It grew quickly and changed continually according to those who took part.

The group was established in a small town in northern Israel, but technical writers from all over northern and central Israel asked to attend the meetings. Those who came shared information that everyone wanted to know but few were willing to share: rates they charged and payment terms, companies that paid late or not at all, job opportunities that weren’t yet locked up by technical companies. We kept in touch and helped each other between meetings.

Today Elephant is the leading professional organization of technical writers living and working in Israel. In addition to over 40 full members, there is a pool of just under 200 writers and editors who share their salary and freelance rate information, nearly 600 people have login rights to the elephant.org.il site and approximately 3000 unique IDs regularly visit the site.

Our meetings and workshops are all free, with top people presenting pro bono because they believe in what we are doing. Meetings are catered “potluck” with those coming to the meetings each bringing an item of food or drink to share.

Ivan: How did a small town networking group become the central professional organization for an entire country?

Svi: Actually our small town has a major hi-tech park that is the second largest R&D center in northern Israel. Being in a small town helped open doors that would have been more difficult in a major city. For example, local industry hosted many of our meetings in their board rooms and cafeterias.

The owners of a local winery helped us open one meeting with wine tasting and free samples. That same winery later hosted two meetings and gives members of Elephant a discount on wine. Making local industry an integral part of Elephant gave us a better perspective of our employers’ and customers’ needs. The mayor of the town even took an interest and offered us the use of the City Hall meeting room after seeing 70 technical writers packed into the cafeteria of a local company.

The word soon spread and people from other parts of the country kept coming back and brought colleagues. Between meetings we originally stayed in contact by telephone and email until we eventually opened the elephant.org.il site to provide a better way to keep in contact and announce meetings.

Ivan: Have you accomplished what you set out to do?

Svi: The original mission was to get experienced technical writers back to work at reasonable rates and to keep competition friendly.

At the time, the competition for the few available jobs was so great that the friendly nature of competition and cooperation among technical writers was beginning to unravel as everyone working feared for their jobs and those looking for work found themselves competing on the basis of price only.

By working together we gave ourselves the competitive edge that we needed in order to get jobs before technical writing companies could. When the technical writing companies have the chance, they lock up available jobs with long-term contracts at low rates and then subcontract to experienced writers who needed the work at any price.

Despite the obvious conflict of interest, we invited local technical writing companies to our meetings and found ways to cooperate for the benefit of all. And it worked. Those associated with Elephant got back to work faster than others and we quickly found ourselves overbooked.

Ivan: Once the economy turned around there really wasn’t any need for this organization, was there? Did its mission change?

Svi: As the economy changed, so did our mission. We went from getting back to work, to maximizing our potential by matching people with the jobs they like most and do best. This was good for everyone: writers, employers, and customers alike. It is always much easier to justify a raise when you provide more value. We also tried to leverage the organization to arrange for discounts on courses and other things.

Our meetings began to turn into workshops and we found that we provided each other with a sort of community that helped us outside the workplace. We worked with other volunteer groups who came to some of our meetings to recruit volunteers. One of these volunteers ran the local branch of an organization that sells donated second hand items to those in need. Their policy of selling at affordable prices rather than giving things free eventually helped serve as a model for the most recent mission of Elephant – “professional empowerment”.

Ivan: What you mean by “professional empowerment”?

Svi: Providing professional services that are not economically viable for the private sector and cannot be provided reliably by the charitable sector. Our meetings are still free and there is still a place for those unable or unwilling to pay, but we also have added-value member services that are not free. Membership is inexpensive, but it is important that people pay even a small amount because it gives you a stake in the organization.

Even participants in our salary and rate surveys need to pay a small annual fee to access the results so that we can provide much more accurate and detailed information than free anonymous surveys can. Many participate without currently having access to the results because it is important to them that the information will be available and affordable for them if and when they need it. Hi-tech companies who purchase accurate information from companies like Radford and Zviran used to be in a much better bargaining position when hiring and during salary reviews. Having accurate information levels the playing field for technical writers in Israel.

Ivan: Could you tell us a little about your background and how you got started as a technical writer?

Svi: After completing my military service in Israel I needed a job and  two of the founders of a data communications company in northern Israel needed technical documentation in English. They were willing to train me on the job because the shortage of native English speakers  was so great. These were some of the best and the brightest in their field; they knew the product, the technology and the market well. Since that time I have nearly always been in a position of opportunity to experiment and learn by trial and error because whenever a new challenge came along everyone else had just a little bit less relevant experience.

During the first 10 years I mostly documented hardware and firmware. I worked with all departments and prepared everything from data sheets, user guides, site preparation, test instructions and electrical drawings to presentations to potential investors.

Ivan: Can you actually make documentation a “painless process” for programmers and engineers?  Where did your technique come from?

Svi: In the early 1990s I became heavily involved in product design and development as part of a small team charged with developing an off-the-shelf hardware/software product for time & attendance and access control that could be sold to and self-installed by small businesses. As the product’s design and features were discussed, I prepared user documentation based on my understanding of how I thought the product would work.

This made it easier for other members of the team to flesh out their ideas. The document was updated constantly and was ready with the product. All information was gained “painlessly” — without, for example, requiring programmers to explain what they had already done. I’ve basically used variations of this process ever since.

Ivan: What variations?

Svi: In some cases I interview the developers and prepare the relevant documents. In other cases I gather most information from existing documents, separate out the unnecessary information and forward questions to the relevant people. Then there are cases where I simply help developers prepare their own internal documentation.

Currently I am working as part of team of experienced writers that prepares service documents for complex and very expensive medical equipment. Medical equipment is a highly regulated field, so the documentation process is nearly as important as the documentation itself. Each member of the team has things to learn and teach the others. My special contribution to the team has been to introduce automation into the documentation process, while other members of the team have taught me a thing or two about document management in a regulated environment. A lot of work is spent making sure each document is perfect because after the release to the field, preparing an updated version is time consuming even for the most minor of changes.

And last, but not least, I spend a lot of my time learning. In many ways I am a “professional student”. I am paid to learn, and put what I learn into a document that teaches others what they need to know.

Ivan: US technical writers have suffered in the recession with many still out of work. What opportunities are there for technical writers in Israel? Has the IT industry been hit as hard as in the US?

A: Israel is a small country with the 2^nd largest number of startups worldwide and the highest concentration outside of the Silicon Valley which means that demand for experienced technical writers is high. Technical writing in Israel is probably more varied than in the US and other places around the world because our skill set also includes “providing English-language services”. This provides entry level opportunities that don’t exist in an English speaking country, alternate uses for technical writers during slowdowns and cutbacks, and opens doors to experienced technical writers that wouldn’t normally exist because their input is often needed by others in the organization that wouldn’t otherwise consult them.

• Both Sillicon Valley and Israel share energized entrepreneurial spirit, informal work atmosphere, pioneering risk-taking ethos and a large number of high-quality immigrants.
• 400 Israeli start ups emerge annually, more than any European country.
• Funded startups has doubled since 2000.
• Next to the US, Israel has more stocks traded on NASDAQ than any other country. High tech (which is minimally vulnerable to terrorism and political instability) accounts to 50% of Israel’s exports – about $15BN annually.
• Israeli companies have easier access to Asian markets, since they are not perceived as a commercial threat.See http://www.vccafe.com/2007/12/10/israel-second-largest-concentration-of-startups-per-capita-following-silicon-valley/#ixzz0euk0s69m

Top technical writers at the high end can command the same respect and even salaries as development team leaders, even as lone writers. During a high-tech recession like the present one many Israeli technical writers are better positioned than their US counterparts to fulfill additional functions until the storm blows over, but they are definitely hurt by the recession. Many have either lost their jobs or had hours and benefits cut back.

Salaries and freelance rates have dropped somewhat, but the impact has not been as great as expected. My theory is that newcomers to the field and inexperienced technical writers have been hardest hit, with more experienced writers replacing them at more or less the same rates. The technical writing companies seem to have been hit harder than independent contractors because they usually have less experienced people and it is easier to cut back on work to a company than an individual.

Furthermore, Israel has not yet been hit as hard by the recession as the US. The financial papers are full of explanations as to why. One is that Israel is such a small market that all of its high tech is export oriented, and North America is not its only target market (though it is the largest). Other reasons include the relatively conservative policies of Stanley Fisher who heads the Bank of Israel and bank reforms that led to higher mortgage equity rates well before the current crisis.

Ivan: To those considering contracting or possibly re-locating to Israel, what advice would you give? Are there websites that offer technical writing jobs, or recruitment firms that specialize in technical communications?
Svi: Immigrants, especially from English speaking countries. actually make up the bulk of Israeli technical writers. Many people go into technical writing after moving to Israel or in preparation for a move to Israel. Hebrew is often important for gathering information, but there are many technical writers who barely speak Hebrew and still manage. Even Israeli-born technical writers write mostly in English. Russian speakers also have an advantage because many of Israel’s technologists immigrated from Russia and other parts of the former Soviet Union.

As freelance rates and salaries for technical writers increase and approach US levels Israel may have already become an attractive place for foreign contractors or relocation. However, most relocation of technical writers to Israel is not for financial or career advancement, but for personal reasons.

Israel is a small country with many people who truly want to help. The most important advice that I can give is to make contacts before even coming to Israel. There is even a government ministry whose sole job is to make it easier for new immigrants. To get a feel for some of the absurdities of life in Israel and the difficulties you are likely to encounter, you may want to take a look at http://elephant.org.il/columns/chelm/ or http://elephant.org.il/life_as_a_tech_writer/ .

If you are looking for freelance work, try contacting potential customers and building up a local reputation while still abroad even though you are not likely to actually close with a customer before you arrive. One way to build up a local reputation is to join Elephant and write a column about a professional topic that you know well, or to take part in some of the mailing list forums in Israel, like CIWI, Techshoret, Digital Eve or COandPI. For a more complete list, see http://elephant.org.il/salarybenefits/freelancers_toolbox.html.

Other resources that you might want to look at are:

• STC-Israel Chapter
• Computer Jobs in Israel
• AACI (Association of Americans and Canadians in Israel)
• Employment Index of Nefesh B’Nefesh (Nefesh B’Nefesh is a private organization promoting Aliya from North  America (US & Canada), and England. In the US and Israel, they work together with the Jewish Agency to streamline  the process and provide additional resources including financial assistance and post aliyah support (social services and job hunting assistance) above and beyond those of the Jewish Agency.)
• Gavahim (Gavahim project’s mission to encourage a growing number of talented professionals to make Aliyah by assisting graduates from foreign universities with the job hunt. Gvahim charges a fee for some of their services.)
• Israel Business Directory of Hareshima
• Digital Eve (email list for Israeli businesswomen, but also useful for men)
• Working Moms in Israel (Email list focusing on jobs that are part time or offer flexible working hours)
• Janglo (Jerusalem area) and Tanglo (Tel-Aviv area)
• www.toshav-hozer.co.il (for former Israelis who want to return)
• www.science.co.il (Israel’s Science and Technology Home Page; links to a wide range of industries such as banking and finance, biotech, academic institutions, etc.)
• Israel Life Science Industry’s site (contains a listing of companies in fields such as biotech, pharmaceuticals, medical devices, etc.)

Ivan: Scott Able makes the point that, “we don’t even do much technical writing any more. And, we’re not going to. We’re consultants, strategists, advisors, teachers, trainers, and more. Content is what we care about, technical content, or otherwise”.

How do you see the role of technical writers changing in the next 5 years? Do technical writers need to see themselves as more than just a ‘writer’ or look at other ways that can add value?

[Scott comments are here: http://www.ivanwalsh.com/2009/10/top-50-technical-writers-on-the-web/]

Svi: I think the profession will continue to grow and change. For many of the high-end technical writers Scott is correct; we message the organization to produce the documentation more than actually write it. In many cases we actually impact on the product to make it more intuitive and maintainable with less documentation. I think that this trend will change, along with more emphasis on non-textual and non-print media.

Globalization and EU requirements that documentation and UI be in the local language will push us toward more non-textual documentation, like the little one-page foldouts in Japanese made products. Short movie clips can played nearly everywhere on laptops, cell phones and even iPods. Knowing how to create a clip will become as common a skill set as typing, so our added value will have to be knowledge of what to show and how to organize the information for the target audience. This really is no different than what we really do now. Any idiot can write “step 1… step 2…”, but identifying the needs of the target audience and separating out the trivial from the useful information is a professional skill.

Ivan: Finally, what advice would you give to those, for example, colleague graduates, considering a career in technical writing?

Svi: Technical writing is a young and constantly changing profession. If you have a talent – use it. I know of one technical writer with such a sense of humor that she can make even the more boring topic memorable. If I could combine her talent with a cartoonist I would make service manuals that people would read in their spare time, and remember exactly what to do and what not to do. On the other hand, if I had her talent I would probably write sitcoms. The point is, that…

Thanks again, Svi, for taking the time.

You can read more about Svi here: http://elephant.org.il/who_are_we/svi_ben-elya.html.

I hope you enjoyed this interview. If you’d like to be included – don’t be shy! – please drop me a line. Please sign up for our Newsletter (top right of page) and get the best Technical Writing tips into your inbox every week.

Image credits: thanks to Jaime Silva

One of the threads on LinkedIn is how to write technical documentation for APIs. It’s been many years since I’ve documented an API (Java & Oracle) so if you have any thoughts on the best way to do this, then please jump in.

An application programming interface (API) is an interface implemented by a software program to enable interaction with other software, much in the same way that a user interface facilitates interaction between humans and computers.

What is an API?

APIs are implemented by applications, libraries and operating systems to determine the vocabulary and calling conventions the programmer should employ to use their services. It may include specifications for routines, data structures, object classes and protocols used to communicate between the consumer and implementer of the API. Wikipedia

Concept

An API is an abstraction that defines and describes an interface for the interaction with a set of functions used by components of a software system. The software that provides the functions described by an API is said to be an implementation of the API.

An API can be:

1. Generic — the full set of API that are bundled in the libraries of a programming language (e.g. the standard Template Library in C++ or the Java API)
2. Specific — meant to address a specific problem, like the Google MAPs API or the Java API for XML Web Services.
3. Language-dependent — available only in a given programming language. It is only available by using the syntax and elements of that language to make the API convenient to use in this context.
4. Language-independent — written in a way that means it can be called from several programming languages. This is a desired feature for a service-oriented API that is not bound to a specific process or system and may be provided as remote procedure calls or web services.

For example, a website that allows users to review local restaurants is able to layer their reviews over maps taken from Google Maps, because Google Maps has an API that allows it. Google Maps’ API controls what information a third-party site can grab, and what can be done with it.

“API” may be used to refer to a complete interface, a single function, or even a set of multiple APIs provided by an organization. Thus, the scope of meaning is usually determined by the person or document that communicates the information.

API Guidelines

Here are some sites that offer guidelines and examples of API documentation.

• API Writing – http://api-writing.blogspot.com/
• Dustin Diaz, API Writing Tips – http://www.dustindiaz.com/api-writing-tips/
• Rajeev Jain, Developing your First API Guide – http://www.stc-india.org/conferences/2006/agenda_web.htm
• Sun API Documentation – http://java.sun.com/j2se/1.4.2/docs/api/
• API Documentation Trends and Opportunities – http://www.stc-india.org/conferences/2004/PprPrest/Conf_Rajeev.htm
• Susan W Gallagher, What are APIs and SDKs – http://members.cox.net/susanwg/susanwg/api.html
• Generating API documentation in HTML format – http://java.sun.com/j2se/javadoc/index.jsp

Twitter’s API Documentation

Twitter has done a great job documenting its API and breaks out all the different component.

“The Twitter API consists of three parts: two REST APIs and a Streaming API. The two distinct REST APIs are entirely due to history. Summize, Inc. was originally an independent company that provided search capability for Twitter data. The Streaming API is distinct from the two REST APIs as Streaming supports long-lived connections on a different architecture.” http://apiwiki.twitter.com

Tips for writing API documentation

What advice would you give to someone writing their first API document set? What mistakes do technical writers make when approaching this area?

FYI: Twitter API: Up and Running: Learn How to Build Applications with the Twitter API

Let’s say you’re setting up a new Tech Docs Dept. You need to create new guidelines, style guides and naming conventions. Should you call the user ‘documents’ User Guides or User Manuals? Which one is Right?

I was asked this question by a colleague in India who is setting up a Technical Publishing Dept in Bangalore.  He wants to go with user guide—me too, actually.

1. When I worked in the UK, it was (mostly) referred to as a User Manual.
2. Whereas in the US, it was a User Guide. I think the Americans (and me!) like things to be short and to the point. Guide is just that little bit quicker to write, especially when you’re creating MS  Word templates.

Saying that, there is no right and wrong, but I did a little fact finding first.

What Google says about User Guides

I searched Google and came up with these results.

• 15,600,000 for “user guide”
• 10,700,000 for “user manual”
• 5,210,000 for “user’s guide”

What surprised me here was that User’s Guide was so widely used. I’ve always found this a bit annoying. I just don’t like apostrophes, I guess.

Top 5 Most Popular User Guides

A quick check on the most popular user guides showed the following. Not what I expected.

• Google Earth User Guide – http://earth.google.com/userguide/v4/
• iPhone User s Guide – http://manuals.info.apple.com/en/iphone_user_guide.pdf
• Patron User Guide – www.ebrary.com/corp/…/en/User_Guide/ebrary_Patron_User_Guide.pdf
• Adobe Reader Help – www.adobe.com/products/acrobat/pdfs/acrruserguide.pdf
• User Guide Tutorial – www.klariti.com/technical…/User-Guides-Tutorial.shtml

IBM Technical Documents

Next, I checked IBM and Microsoft  to see what term they used.

• 15,324 for user guide
• 1,047 for user manual

So, they prefer user guide. Though, you’d think they’d make this mandatory. Of course, it’s not easy when you have offices in every corner of the world, so let’s cut them some slack.

Microsoft prefers User Guides too

The folks are Redmond were more consistent with

• 1.8 million for User Guides and only
• 73k for User Manuals

And, to be fair, many of the user manuals were actually guides when I checked. Someone check that search engine!

Is Apple different?

Yes, of course.

Apple prefers the term User’s Guide. Like I said, I never bought into this. I prefer short, snappy titles. We don’t call them System Administrator’s Guide, do we?

Well, of course, some do.

Things to consider when naming your documents

• Avoid obscure or unique terms for your documents. Use industry standard terminology.
• Ask your target audience what they expect.
• Create a Style Guide or adopt one, e.g. the Microsoft or IBM style guide.
• Develop a naming convention, e.g. a structure approach so that all documents are named, filed, and indexed correctly.
• Develop a numbering convention. Show people how to number documents, for example, when to go from 1.1  to 1.2 and when to go from 1.2 to 2.0.
• Be consistent.
• Be patient when they get it wrong.

My career really began to take off when I saw myself as an ‘enabler’ rather than a writer. My identity of who I was changed from a guy who cranked out docs to someone who helps others get their projects done.

People want to learn, do your best to help them get there.

What do you think? What’s the most practical way to name documents and setup a new Technical Writing Dept?

Maybe you don’t hear your accent, but others do. When you read their documents, does the accent come through?

We all judge people by how they speak. It’s easy.

When I was a kid, I had a strong regional accent. I grew up near the countryside and thought that was the way people spoke. Well, we all did.

When I went to college, a teacher told us to polish our accents if we wanted to get ahead. He was right.

Name one CEO or world figure with a strong regional accent? It gets ironed out along the way.

Today, I have hardly any accent.

Years of trying to smooth out the rough edges and blend in have diluted what was there. Most think I’m American, French (dunno!) or Russian (they go by the name, I guess).

Seth Godin asks if your writing has an accent?

“Of course it can. Not just grammar errors, but sentence length, exclamation marks and your vocabulary all tag you. And the fonts, colors, pictures and layouts you choose are part of your accent as well.”

So, here’s my question.

When you review other people’s documents, what can you tell about them? Does the way they ‘speak’ influence the decisions you make based on their material?

Flip it around.

When they read your documents, what do they think?

One of our tech docs team was fired yesterday. Why? Technical documents provide no value.

This is how Management sees it.

Tech docs are nice to have but NOT essential.

Tech docs are useful but LESS important than development, user interface and marketing.

Are they right?

It’s hard not to get defensive in these situations. But maybe they have a point.

I was asked – “what metrics do you use to tell if the documents are successful?”

I did.

But they didn’t like (or agree) with my interpretation.

Do you even have any metrics?

How can you tell (objectively) that your documents are worth the money?

If not, maybe you next to be called into the office.

“Look , your documents are great but…”