Re: [twin] Course Content for Technical Writing

Hi
Your hard skills are okay. But you are not specific when you say 'team
skills' I mean today everyone is expected to be a team player so it is not
necessarily a skill you know? I'd rather focus on specific skills
like 'interviewing skills' and 'survey skills': a tech writer spends lot of
time interviewing subject matter experts and technicians to collect
information.
And on the technical front I strongly recommend they understand and learn
SGML, XML, HTML (stuff like the docbook DTDs is important). They have to
understand Mark up languages in order to write something that can be
published anywhere (cross platform). You may want to add in tools like
robohelp, framemaker PLUS a basic course on 'help' formats (winhelp, java
help, htmlhelp and so on).
A technical writer writes to an audience so her work has to be user-friendly
so you may want to include a primer on usability and usability testing. (I
can provide material on this)
I think a good technical writer is one that is not afraid of code, that is
ready to skim through reams of material, one that loves talking to people,
one that knows the rules of the language and knows when to break them. And
finally one that loves to write. And understand what 'being objective' is.

Hamsila wrote:
>
>Hi All
>
>I have been asked to help develop a post graduate diploma in Technical
>writing. This could possibly train novices in the field or those wishing to
>take up Technical writing as a career.
>
>As I see it, there are two sets of skills required:
>Hard Skills:
> Language
> Tools
> Editing
> Proofreading
>
>Soft Skills:
> Interpersonal skills
> Team skills
> Research skills
> Motivational skills
>
>Is there anything else that could be included?
>
>Regards
>Hamsila
>
>
>
>..........................000000000000................................
>Send messages to: twin@user.itconsult.co.uk
>
>Leave TWIN: Send blank email to twin-leave@user.itconsult.co.uk
>Join TWIN: Send blank email to twin-join@user.itconsult.co.uk
>Digest Mode: Send blank email to twin-digest@user.itconsult.co.uk
>
>Post Job-Ads: Send job-ad to: twinjobs@user.itconsult.co.uk
>
>List Owner: twin-owner@user.itconsult.co.uk
>TWIN Website: http://www.twin-india.org
>TWIN Archive: http://user.itconsult.co.uk/twin/archive/
>
>
>

Read More

Latin Words Used in The English Language

Trust me, you’d feel like an oaf when someone rattles out a Latin phrase like ‘Sine Qua Non’ or ‘Summa Cum Laude’ and it goes over your head. You just grin, not indicating whether you understood the damn phrase or not. That’s definitely not the position I want you in -perverts may ignore the pun- So, here today I bring you a collection of oft-used Latin phrases in English language. Did I hear a collective sigh of relief? All right, all right don’t cry now and tell me ‘Suman What’d we have done without you!’ So, as I walk into the bright orange sun-set like the traditional hero... You guys go take a look at the Latin phrases. It’s ‘Sine Qua Non’ baby!

http://depthome.brooklyn.cuny.edu/classics/englatin.htm

write to me: Suman@sumankumar.com

Read More

Importing Word2000 Documents to RoboHelp HTML

Article on Robohelp Community


Above article in Flash-help format

write to me: Suman@sumankumar.com

Read More

How to hire a 'Future-Proof' Technical Writer

I came across quite a few recruitment ads in the papers and job announcements in mailing lists that ask for a technical writer. It is good to see that the demand for my ilk has shot up. What’s appalling though is the emphasis that the companies place on a tool: ‘should be acquainted with ‘ALL’ features of FrameMaker’ or ‘experience in writing for semi-conductor chips a must’.

Here’s my take:

My complaint is very few of them actually are bothered about writing skills. I know that writing skills alone don’t make a good technical writer. A good perspective of technology and writing (to an audience) skills do.

I’ll speak for the IT industry: A tech writer should NOT be code-phobic. She should have excellent interviewing skills. Should be a friend. Should have a lot of patience (your SME can get on your nerves I am telling you). She must die for her users… (your boss may slap your back and say ‘atta girl! It’s looking great.’ But if your user doesn’t understand what you’ve written or can’t navigate through your documentation, it is not a blot only on your skills, but also on the product). So writing to an audience is something that I’d look for when I am hiring a technical writer.

Let’s go for the tools now:

Tools change. Say that again aloud. And learning a new tool doesn’t take time. I am positive that any good technical writer can pick up FrameMaker in a week’s time. But being an expert at it? Go for a desktop publishing person man.

I have no problems understanding technology; the APIs, the chips, the front-end processing, the database… I’ll understand it all. I’ll interview your SMEs, I’ll study code, and I’ll move mountains to ensure that the technical nitty-gritty is translated into something that your user understands. But don’t go ‘a technical writer with expertise in FrameMaker, RoboHelp, XML, SGML, HTML, Java, C++…’ Gimme a break will ya?

I am not saying that a reasonable level of expertise in popular (they wont remain popular for long though) tools is not required. What I am saying is, if your candidate were good she’d be comfortable in most of the tools. If she’s not an expert in FrameMaker or Snag IT don’t write her off for god’s sake. Don’t pin your technical documentation to a tool. Pin it to a person. A person that understands the trade, the users… as I said, if need be that person will pick up your tool.

Also, it’d be nice if your technical writer knows how to break the rules. I mean I know a lot of writers who guard the English Grammar with talibanistic zeal. If I were you, I’d bother about the ‘usability’ of the error message than its grammatical integrity.

Let’s summarize it: Don’t confuse writing and publishing. They are two different domains. A good writer needn’t be a great publishing expert. Look for a person with a good technical perspective, impeccable writing skills, user-focus and integrity. If I can’t (wont) stand up for my user, I can go home. So my dear reader, the next time you go shopping for a technical writer, remember “Tools change.”

If you listen to me you’ll get yourself a ‘Future-proof’ technical writer. If you didn’t you got yourself a Johnny. And I won’t be surprised. ;-)



Related Links:

FrameMaker
RoboHelp
SnagIt
AuthorIT
Irfanview
HTML Kit
Swish

[Note: There are a million tools out there. I have listed what I use.]



write to me: Suman@sumankumar.com

Read More

AECMA Simplified English

What Is Simplified English?

AECMA Simplified English is a writing standard for aerospace maintenance documentation. This type of writing standard is also known as a controlled language because it restricts grammar, style and vocabulary to a subset of the English language. The main characteristics of the Simplified English standard are

Simplified grammar and style rules.

• A limited set of approved vocabulary with restricted meanings.
  
  
• A thesaurus of frequently used terms and suggested alternatives.
  
  
• Guidelines for adding new technical words to the approved vocabulary.
  
  
• The objective of Simplified English is clear, unambiguous writing.
• Developed primarily for non-native English speakers, it is also known to improve the readability of maintenance text for native speakers.
  
  
• AECMA Simplified English does not attempt to define English grammar or prescribe correct English. It does attempt to limit the range of English; many of its rules are recommendations found in technical writing textbooks. For example, SE requires writers to:
  
  
  
  
  
  • Use the active voice.
    
    
  • Use articles wherever possible.
    
    
  • Use simple verb tenses.
    
    
  • Use language consistently.
    
    
  • Avoid lengthy compound words.
    
    
  • Use relatively short sentences.

Other Controlled Languages

While AECMA Simplified English is designed for use in aerospace maintenance documentation, controlled languages can be created for other writing domains. Companies in several industries -- manufacturing, mining, oil exploration and software development, for example -- have modified AECMA Simplified English or produced their own controlled-language writing standards. The Boeing Simplified English Checker can be modified to support more general technical writing.

Related Sites:

AECMA (European Association of Aerospace industries)


simplified English




write to me: Suman@sumankumar.com

Read More

And now, 'Technical Writer': The Movie

And now, 'Technical Writer': The Movie

A
movie on a technical writer!
[Through Usable Help]

Read More

A Tale of a Technical Writer who did Programming for Fun

A Tale of a Technical Writer who did Programming for Fun

V Srinivas on the TWIN list wrote:

Hello Twinners,

I must say I have been keenly following the views and opinions that have
been coming up regarding the usage of online help tools.

First of all, I would like to say that I wouldn?t want to spend much time
in ?creating? an online help file. I would rather spend time
in ?improvising? and ?thinking? about how I can make that Help file reach
the audience better. And that too, I would want to have some TIME on my
hands to do that.
I definitely wouldn?t want to spend precious time in doing work such as
copying and pasting.

>From my experiences, I can roughly put down the following statistics
relating to the thought process and labour that goes into creating manuals
and online help.

Creation of a User Manual may involve: 100% Thought Process Creation of
Online Help may involve: 10% Thought Process + 90% Labour / Mechanical Work

Which means, most of the time has been spent in copying and pasting content,
creating HTML files, building TOCs, creating indexes and so on. And
annoyingly, I was all the time aware that they are already there in the
user?s guide and that I was doing the same thing again. Sure, there are
tools in the market that can take care of the 90% labour but we are a little
wary of the price tag. Also, I have been a size fanatic. I have always
wanted my HTML files (and the resultant CHM) to be as compact as possible.
To add a few more wishes, I wanted them as ?readable? and ?editable? as
possible. In other words, I didn?t want a thousand unnecessary HTML tags to
get stuck in my document. For a live demonstration, just convert your
document to HTML using Microsoft Word So I started using RoboHelp. RoboHelp
was good ? with its good user
interfaces and other powerful features. But again, it was the same old
story. I had to still do the copying and pasting, which I loathed so much. I
still had to build a TOC (when in reality, I already have done the thinking
in structuring the TOC in Word itself) and I had to still worry about
getting the images right and stuff like that.

So, I abandoned these tools altogether and started working with the HTML
code itself. For this, I wrote small macros in Word to start tagging the
document manually. So, for about six months, I depended on two major tools:
1. MS HTML Help Workshop (for its simplicity) 2. MS Word
But I was not happy. For example, for a 75-page user?s guide, I took almost
about 3 and half-hours to convert it to online help. I will not bother to
tell you how much time I generally take for converting a 233 page user?s
guide.

Automation was the only answer. And I jumped to the occasion. For a start, I
started examining behind the scenes of a .HHP project ? how the project was
being structured, how the TOCs were structured, the indexes and so on. I had
a fair idea about the HTML part of it, because I was manually tagging the
document.

I used Microsoft Visual Basic to experiment on simply because it was so easy
to understand. One afternoon, I started playing with a Word object and
slowly but surely, my dream of automating user manuals to online help turned
into reality in the weeks to come. Some parts of it were tough and bothered
me even in my sleep but I must say, that it was a lot of fun solving one
mystery after the other. I should say, identifying and tagging the bulleted
lists and numbered lists really did bother me a lot.

BUT I DID IT!

On the afternoon of July 25th, 2003, I couldn?t help feeling a little
elated. I fed a user manual (65 pages) to my program and it took exactly 4
minutes to do all the conversions and present me the online help project on
a platter (.HHP). Another 3 seconds to compile the project and I was THROUGH!

Sure, there are still some downsides to the conversion process that I am
working on ? for example, the program is getting a little confused when it
tries to convert a table, which has merged rows/columns. Also, my program
requires that all the images should be linked to external files. I should
perhaps find a way to pick the image (linked or not) inserted in a word file
and save it to a JPEG ? now that would be something. Another downside is
that it can generate only two levels of TOC. I can in fact defend myself
saying that after the second level, it is up to us to decide whether some
content needs to be grouped into a third level and so on.

But the fact is, the program (HTML Help Express) at least gives a good kick-
start to my whole process of creating online help. It may not be the best in
the industry, but hey, it?s a solution. It can prove to be a fairly decent
in-house tool for technical writers in our company and I had a fantastic
time in developing this. And of course, I had a fantastic time in my company
explaining politely to everybody that it was a TECHNICAL WRITER who
developed the software.

So who said that Technical Writers are ?not? technical? Who says that it is
only ?they? who develop and we ?just? write? Technical Writing has been
recognized as an IT enabled service. And I feel that while we write about IT
products, we should also simultaneously use the power of IT to improve and
automate our own work processes.

Regards
V. Srinivas

Read More