Online groups, autumn 2011

Wikis for documentation

Some members think that wikis are useful for documentation, but other members do not agree.

One member thinks that editing a wiki is difficult and can confuse people who do not use the wiki regularly, because the methods of mark up are unusual. Usually, when people edit a wiki, the result is not good. "Even Wikipedia has a hard core of 'subject editors'… [who] periodically go in and tidy up the bad writing and misinformation left by others."

Some members think that software developers are happy to write for wikis, because writing for a wiki is different from writing documentation. After the content is reviewed, a technical communicator can use the content to create other documentation.

One member likes Confluence (www.atlassian.com/software/confluence) and MindTouch TCS (www.mindtouch.com), because he can use them in a similar way to Word. Confluence and MindTouch TCS are designed for technical documentation, but they are less complex than most help authoring tools. However, the programs do not have the features that are in most help authoring tools for managing links and for creating a table of contents.

Another member does not like Confluence. "The Wiki markup syntax is ill-thought out and confusing, the editing and page maintenance tools are poor and have a very confusing user interface, and the help documentation is really bad."

To help with publishing to Word, one member used the Scroll Office plug-in for Confluence (www.k15t.com/display/TDWIKI/Scroll+Office). "Both Confluence and Scroll Office may be limited if you're doing complex tasks, but I found them reasonably easy and clear to write short user manuals."

Members suggested the following resources:

Reading Kindle e-books

To read a Kindle e-book, a Kindle reader is not necessary. Amazon supplies free software that lets people read Kindle e-books on different operating systems such as Windows, Mac OS X, and Linux. Download the software from www.amazon.com/gp/feature.html/ref=kcp_pc_mkt_lnd?docId=1000493771.

Writers, authors, or communicators?

A member started to look for freelance work. She thinks that most people do not know what a technical writer does. What terms do technical communicators use to explain what they do?

When a member wrote manuals, the term 'technical author' gave good results. However, now he has work from charities. He records business processes, writes funding applications, and creates websites. People in charities do not know the term 'technical author'. He has better results if he uses the term 'technical communicator'. Make sure that your website and brochures include all possible descriptions of what you do. Explain how your skills let you solve many communication problems.

Another member wrote, "I call myself whatever they want to read, Author or Communicator (as I do training as well I prefer Communicator)."

In 2005, someone asked a similar question on the IASIG list. For a summary of the discussion, see www.techscribe.co.uk/ta/describing.htm.

Abelard Consulting in Australia asked a similar question in a web-based survey. The November 2009 issue of Words has the results of the survey in 'What should technical writing be called?: survey results' (www.abelard.com.au/words-1-4.pdf).

Adobe AIR

A member wants to use RoboHelp version 8 to create context-sensitive help with Adobe AIR.

The process is dependent on the type of help:

Good information is on www.grainge.org/pages/authoring/air/8/air_rh8.htm.

|

RSS feed