Importing Word2000 Documents to RoboHelp HTML
Article on Robohelp Community
Above article in Flash-help format
write to me: Suman@sumankumar.com
Tuesday, 12 August 2003
Sunday, 10 August 2003
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
Friday, 8 August 2003
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.
- Use the active voice.
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
Saturday, 2 August 2003
A Tale of a Technical Writer who did Programming for Fun
Posted on 05:41 by Unknown
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
Tuesday, 29 July 2003
PowerPoint Resources
Excellent site for some real cool 'free' templates; and for some essential tips and tricks. Betty sure is Brainy! Check it out.
http://www.brainybetty.com/PPTIndex.htm
write to me: Suman@sumankumar.com
Wednesday, 2 July 2003
Using Blogs to Collect Information
I am experimenting this idea. I have set-up a blog (using Nucleus. This is what I did:
1) Met all the technicians I had to.
2) Told them about how they can provide information now through a browser based 'site' that'd allow them to 'blog' their ideas/suggestions
3)I created user ids for all of them for the Intranet blog and mailed them the same
4) I also told them they can use the 'right-click to blog' idea. Like Blogger, Nucleus offers a 'right-click->Blog this' feature
It's worked out ok for me. I mean not all took to the idea. But some did. That's a start! Have you tried something like that?
Subscribe to:
Posts (Atom)
