Bits & Brains

Writing the right stuff, the right way

2011-06-23T10:16:00.000-07:00

The following article was first published in June 2011 edition of Orange Byte, the quarterly newsletter of Persistent Systems, Nagpur.

-------------------------------------------------------------------------------------------

Writing the right stuff, the right way

Technical writers, along with testers, live a fire-fighting life. Last-minute changes, review comments, functionality enhancements, user interface changes keep us on our toes all the time. Of course, in some cases, this situation is due to external factors beyond our control, for example, a sudden change in client requirement. But more often than not, it results from our own improper handling of tasks.

The irony of the situation is: many of us actually relish this kind of work-ethic. It makes the job exciting, makes us feel superheroes, fighting the odds and winning at the last moment. No one gets thrilled about any activity that sails smoothly… In the public eye, hero is the one who hits the last ball for a six, even though he may have played lethargically all through the game!

Personally, I have grown wary of this kind of mindset. Documentation is now a well-established arm of IT industry. It is time for us to move on to a more stream-lined, more ‘professional’ approach; one that will not enable us to consistently meet the ever-increasing expectations but will also bring about a healthy work-life balance.

While pondering over this a few months ago, I came across an article titled, “They write the right stuff” published in the Fast Company magazine. The author described how a small team of 250 people writes the phenomenally complex software that controls a space shuttle, and how they get it right every time. The interesting point is: This team is not made of high-energy, cowboy-styled geeks, but rather just the opposite. Here is what how the author describes the environment:

“It's strictly an 8-to-5 kind of place -- there are late nights, but they're the exception. The programmers are intense, but low-key. They're adults, with spouses and kids and lives beyond their remarkable software program.

The shuttle group produces grown-up software, and the way they do it is by being grown-ups. It may not be sexy, it may not be a coding ego-trip -- but it is the future of software. When you're ready to take the next step -- when you have to write perfect software instead of software that's just good enough -- then it's time to grow up.”

So how does this team manage to be the complete antithesis of a typical software group, and yet produce what is possibly the most perfect piece of software anyone has ever written?

“The answer is: it's the process. The group's most important creation is not the perfect software they write -- it's the process they invented that writes the perfect software.

It's the process that allows them to live normal lives, to set deadlines they actually meet, to stay on budget, to deliver software that does exactly what it promises. It's the process that defines what these coders in the flat plains of southeast suburban Houston know that everyone else in the software world is still groping for. It's the process that offers a template for any creative enterprise that's looking for a method to produce consistent - and consistently improving -- quality.”

The article goes on describe the key highlights of this process, which admittedly seem quite simple and obvious. And yet, the fact remains that no other software outfit has achieved the same kind of perfection in creating the software.

The article has fascinated me, and made me think about how documentation can be performed the same way. How do we write the right stuff in the right way? How do we integrate passion with process to deliver a perfect product, time and again?

To be honest, I do not know… yet.

Checklists: A technical writer's perspective

2010-06-08T06:50:00.000-07:00

[This is a companion article to my review of "The Checklist Manifesto", posted at GReviewz. You can read my personal take on checklist on Mind Matters blog.]

For a technical writer, reading The Checklist Manifesto by Atul Gawande is sure to give a feeling of been there, done that... in a good-natured way, of course. We are possibly the ones who are most familiar with a checklist; for, more often than not, we are the ones who create them.

When I joined Infospectrum as a technical writer, I didn't have much experience in the field, apart from what was gained by surfing the net, reading a couple of textbooks; and talking to a few senior guys. However, it didn't prepare me for the shocks of the practical office life. Our client was (and still is) very particular about everything when it came to documentation. He nitpicked over the language, and could tell minute differences in fonts just at glance.

To meet his expectations, me and our project Manager Vijay Phulwadhawa, started keeping notes about things that needed to be verified before a document was checked in. It covered a number of things, the logo, the copyright notices, headers and footers, links and cross-references and so on.

We also learnt a few things first-hand. For example, I had used colours to highlight important points; but we realized that the client often printed out the manuals using monochrome printers. So we switched to using different typefaces (Bold, Italics, and Underline) to achieve the same goal.

The checklist proved very useful, and soon we were implementing the idea in other process areas as well. We had an installer checklist, a code review checklist, a product release checklist, and so on.

Of course, I was lucky to have a project manager like Vijay who is himself a methodical person. He not only popularized the concept across the team, but also saw to it that the checklist was used during each phase of the product development. Considering the complexity of the domain and the product, it turned out to be the best thing to do.

So, what are the characteristics of a good checklist?

Well, checklists should conform to the requirements any technical documentation. That is, a checklist should be:

Precise: Accuracy is of paramount importance when creating a checklist, as this is what the product will be validated against.
Concise: No one would dare to use a checklist that spans pages and pages of text. Our product release checklist has about 30 checkpoints, but they are divided among the software programmers, the testers, the technical writers as well as the project managers, hence, each group has to only verify not more than five to six checkpoints.
Up to the date: An outdated checklist is as good as no checklist. Every checklist should be periodically reviewed and updated wherever necessary. A change history should be maintained to identify the modifications.

If you are a technical writer and (yet) feel that using a checklist is so un-cool, think again!
Or better, read The Checklist Manifesto!

My presentations on SlideShare

2010-04-05T23:30:00.000-07:00

A few days ago, I had posted about documentation questionnaire and documentation tools. You can view these articles as PowerPoint presentations on my SlideShare page.

End Users are not dumb users

2010-01-18T06:50:00.000-08:00

One of the first jargon words that a rookie technical writer comes across is the end user. End user is the actual user of the product, and is most of it times, different from the client. Another term, that is often used interchangeably with end user is “layman”.

"Document the application such that even layman can understand” is one of the first doctrines that the tech writer is taught.

Unfortunately,

this sometimes leads to technical documentation that is dumbed down to hilarious levels. An ex-colleague of mine used to explain in detail how to use mouse, what are the different parts of a standard window (the menu bar, the toolbar, etc. ), and so on. It wouldn’t have been an issue, if the document he was creating was supposed to be used by system administrators, people who one can expect to have a fairly advanced knowledge about computers!

Do not use jargon

... is another mantra. Here again, I feel one needs to use the precise terms, with proper explanation, of course. While reviewing a document for marine application, I found the technical author using the term ‘ship’, whereas the operators were used to the term ‘track’ (an icon that represents ships on the screen).

Now, do not get me wrong:

... this is not to say that one should run amok with all sorts of technical terms and write as if only sys-admins will read the manual. The point here is: respect the skill level of end user, especially when you know that they will be expert users.

How does one know the skill level of the end-user?

The target audience

...is one of the important questions that you must ask during information gathering phase of any document. Ask this question to the project manager or better, ask the customer itself. Most of the times, they will be able to give you some idea about the skill level of user.

In some cases,

the target audience is rather obvious from the type of document itself: the reader of an API document can be safely assumed to know at least some basic knowledge about the syntax and the programming language; whereas online help for a school management system needs to be very descriptive as the users are likely to be non-techies.

In the case

....where you have absolutely no clue about what would be the target audience, it is a good idea to ask some of your colleagues (preferably from a different team) to run a quick eye over the document (or a representative sample of it) and gauge if they can make sense of it.

Another way

....you can keep the document simple without making it seem childish is by using extensive cross-referencing: either by embedding hyperlinks (in online documentation), or by pointing to the relevant sections (in print documentation).

And last and most important:

Always include a section on glossary and acronyms/abbreviations in (almost) all the documents that you create.

As one of the greatest physicists, Albert Einstein put it quite succinctly,

“One should always try to make things as simple as possible, but not any simpler.”

Documentation Questionnaire

2010-01-11T06:50:00.000-08:00

Every documentation project starts with information gathering. Since interviewing the subject matter experts is the chief source of information, it is imperative that a tech writer asks the right questions.
Here are some questions that one can ask, irrespective of the type of application, domain or the project.

Questions for Project Manager
The first person you are likely to meet from the team is its project manager. Here are some of the important questions you need to ask the project manager:

Product name: Sounds basic, eh? Well, the project name and the name of the application you will be documenting need not always be the same. Also, sometimes, product names need to be spelled in a specific way due to trademark purposes. Also, be sure to get the name of the customer.
Release date and documentation deadline: Again, these two need not be (and, preferably, should not be) the same. For bigger projects, it is advisable to set deliverable date at least a week prior to the release date. This gives you time to check up context sensitive help.
In some cases, the documentation is delivered after the product release. In this case too, you need to be clear about the deadlines.
Documentation suite: What are the documents to be submitted? A typical documentation suite would consist of installation guide, user manual and a technical reference manual.
Deliverable format: Are the documents needed in PDF format? CHM help? Will the customer also need the source files?
Documentation Scope: What is the expected depth of content in the documents? Should it be very descriptive, or just to-the-point? Contrary to the popular belief that user documentation shouldn't contain jargon, my personal observation is that it is necessary to use precise terminology.
The documentation scope largely depends upon the taget audience. See next point.
Target audience: Who will be the end users of the system? What are the assumptions about the skill level?
Point of Contact and Communication channels: Usually you will interact with the project manager, but he might choose to appoint the team lead or the QA lead as your single point of contact. Ask what would be the medium of communication with the team lead and team members; will it be e-mail, Skype or face-to-face interactions?
Content Management: Does the team use a content management system? VSS? SVN? Be sure to get ask about version control method.
Reference documents: Ask about any available documentation about the product: design documents, understanding documents, etc.
Access to servers, Mailing list, etc: You will also need access to various machines, servers, get your name added to the project mailing list.
Client communication: What is the name of the client? Will you be involved in client communication?

Questions for Team Lead
In large projects, the project manager is likely to delegate the task of documentation communication to either the technical lead or the QA lead. Here are some of the important details you need to get from these people:

Application overview: This is a bird’s eye view of the application and the domain. Ask about the purpose of the application, how exactly it helps the user to accomplish a particular task.
System Overview: Each application consists of a number of components. Ask about how the individual modules interact with each other. Does the application use a database? Does it have a web-component?
System configuration: Inquire about the minimum and recommended hardware and software components necessary to run the application. How RAM is sufficient? What service packs are required?
Names of people and modules: On the people side, get the names of people in team and the modules they will be working on.
Time slot: Rather than going up to the technical lead or QA lead every 10 minutes for doubts, it is better to have a time-slot in which you can get a bunch of questions cleared in one go. In a big project, ask for one hour every week; in a smaller project, ask for half hour every day.

Questions for Developers and QA
As the documentation proceeds, you will be interacting with the individual members of the team: programmers and quality analysts. Apart from the questions specific to the application, here are some general queries that you can ask:

How the modules are linked: How does component A interact with B? And how both of them relate to module C?
Process workflow: Ask about a complete iteration of the process workflow; what are the inputs to the system how the system processes those inputs and what it generates as the output. Using flowcharts, sequence flow diagrams greatly helps.
Bug fixes: Apart from change requests (usually from the customer), the main cause of any change in the product is bug fixes. QA indentify a bug, and developers fix it; sometimes making significant changes either in the functionality or the user interface. How does one keep abreast of it? The best way is to get access to the bug tracker for the project. In large projects, the bugs will be added in a bug-tracking system (such as Gemini, Bugzilla, etc.). In small projects, the team may make do with an Excel sheet that is shared and updated by the team. Whatever the bug-tracker may be, you need to have at least read-access to it.
Troubleshooting: While using the application, you are likely to come across confusing workflows or screens. Put yourself in place of the user, and try to identify the steps you will need to implement for a work-around. Troubleshooting tips are an important part of documentation.

Questions for Networking
In small, non-complex projects, the team members should be able provide you with all the details, even those related to network. However, in big projects, it is a good idea to get your answers straight from the horses’ mouths, in this case the network guys.

Network topology: What is the network topology: is it star, bus, or a composite?
System-specific requirements: Inquire about any specific dependencies about the product. For example in Linux, it is good to have a list of RPM dependencies.
Network requirements: Ask about administrator privileges, bandwidth requirements, firewall settings, and so on.

Questions for Client
It is always a good practice to be directly interacting with the customer: it relives the project manager of undue communication, and resolves many misunderstandings. Here are some questions best answered by the customer.

Document suite
Document structure and templates
Point of contact and Communication channel
US-English/UK English

How the users use Online Help

2009-11-09T22:55:00.000-08:00

A few months back, I had an opportunity to observe users in action while using the help system I had created. Here are some observations from the exercise. It should be noted that the ‘users’ were actually power users of the application, with substantial background about computers. This is not surprising, considering the complex nature of the application.

Here are the observations:

Contrary to the popular belief, users do use the help system at least for the first time when they face a problem. What counts is the ‘first impression’. If they are satisfied with the results, they tend to try the help before reaching out to other users/ tech support.
Users prefer online help to a printed user manual. However, when the users need to follow instructions by referring the manual step-by-step, they prefer to take a printout rather than switching between the application window and the online help.
When users take printouts of help file, they very frequently jot down their remarks and findings in the margins. It would be great for a technical writer to go through these ‘annotated’ help pages and update the help system wherever required.
The most common location where the users look for help is the top-right corner of the application window. Place the link to help at any other location, and you are sure to confuse the users.
Very rarely do the users refer online help for theoretical information. They prefer to have theory in a printed user manual. What the users usually look for in the online help is:

Procedures
What needs to be entered in a particular fieldUsers very rarely use the table of contents. The most preferred way is to type the query directly in the Search tab. The more advanced users try the Index tab before going to Search tab.

Users are generally willing to try a few variations of the keyword or the query phrase. If they still do not find what they are looking for, they get quite frustrated. Also, broken hyperlinks give them fits.
It is necessary to refer to the buttons, labels and captions exactly as they appear on the screen. For example, if a checkbox is labeled as ‘Allow Administrator Rights’, do not refer to it as the ‘Admin rights checkbox’.
Users appreciate it when the help shows them easier ways of accomplishing their tasks. For example: Suggest Start |Run and typing winword than going all the way to Start | Programs | Microsoft Office | Microsoft Word.
Pointers to additional resources, such as “See Also” or “Related Links” are quite useful and often used.
Content is king. There is not much value in wringing one’s hands over whether to use ‘login' or 'log in' – users hardly pay any attention. Choose a particular style – one that is simple and yet clear – and stick to it.
A section on Frequently Encountered Problems or Troubleshooting greatly enhances the value of documentation.
If the application displays error messages that have error codes, it really helps to have a link in the error message itself, directing the user to the section in online help/user guide which explains what the error code means and how to resolve the error.

Blogs & web sites on tech writing

2009-10-08T20:30:00.000-07:00

For the last one year, I was heavily into blogging... I mean, the reading part of it. Here is a list of blogs and web sites on technical writing that I have been visiting with some regularity.
Please note that this is by no means an exhaustive list, and I will keep adding to it in future posts.

Technical Writing blogs

Technical Writing web sites

My interview in company newsletter

2008-06-29T11:00:00.000-07:00

Infospectrum, the company I work for, publishes a monthly newsletter, titled as Pulse. I am a member of its editorial board for last two years. Pulse has a section, “Rendezvous with Roving Reporter” in which we interview an in-house celebrity every month – usually the top brass and the senior project managers. Last month, however, the editorial team caught hold of me unawares and interviewed me for this section. It was a pleasant surprise, as I had completed 2 years at Infospectrum in the very same month.

The excerpts from the interview are as follows:

Describe yourself in one word...
The word that naturally comes to mind is “Intelligent” but some of my friends would vehemently object to it, hence I would say, “Inquisitive”

How did you become a technical writer?I started my career as a programmer in .NET-SQL2000. However, within a short time, there were pangs of dissatisfaction, and realisation dawned that this wasn't something I would be happy doing for life. Writing is my passion and I love computers and technology. After a bit of soul-searching, I decided upon technical writing. Tushar Joshi referred me at Infospectrum. An interview followed, and here I am!

Celebrity Facts
Created first user manual in 11th standard. His class was using Casio 100fx scientific calculator for Physics practicals and couldn’t figure out how to use some of its advanced features. Gautam created a simplified version of official user guide, which turned out to be very useful.

How’s it been working as a technical writer at IIPL?It’s been a learning experience. Over the last two years, IIPL has given me exposure to diverse domains, and an onsite opportunity, which is still something of a rarity for technical writers.
Technical writing is rapidly evolving into a broader field of technical communication. The user documentation itself is morphing into a variety of formats: wikis, blogs, audio-visual aids. We need to adapt ourselves to this change.

Is writing an art or skill?
Writing a novel or a fiction story could be termed as an art, but Technical writing is a science, bound by definite rules. You gather facts about an application, analyze it for what is essential and what is not essential and then lay it down in a language that is stripped off any undue flourish.

Have you ever thought of writing a book? What kind of book it would be?
Aah, writing books (user manuals, reference documents) is what I do for a living! Apart from that…ummm…I would like to try writing a non-fiction book.

Celebrity Facts
A Workaholic!! Comes early to office, usually before 9 AM in the morning, and often hangs around till 9 PM. An extreme case of all work and no play....

Your Role Models
Dr Abdul Kalam: he has shown that you can succeed on pure intelligence and hard work, without having to resort to underhand approaches
Bill Gates: I admire him for his intense passion and an unrelenting focus on his goals
Closer home, I am fascinated by the life story of Dr R A Mashelkar. A poor boy, who literally studied under streetlights on footpath, went on to become Director General of CSIR, world's largest chain of scientific laboratories!

What do you do when you are not in office?
You’d be amazed at the mess you can generate in your room over a week, by simply not doing any of the regular clean-up chores. So, on weekends I have my hands full – laundry to do, and broom to sweep the room.
Occasionally, you would find me drooling over books at Crossword, or watching some movie at multiplex. I am quite an active blogger as well.

Celebrity Facts
A Book Worm!! A voracious reader…Gautam likes to read till late night. As told by his close friend, if you send him an SMS at 1 o’clock in night you are bound to get his reply.

Tell us something about your native place.
I hail from Goa, a beautiful state; with a laid-back life and non-confrontational, live-and-let-live culture. My hometown Ponda (pronounced Fonda) is situated in a valley, just 20 KM away from the seashore. Goa is more than just beaches and booze; this small state has given India some of its brightest jewels, be it in music, art or science.

Celebrity Facts
Gautam loves gardening. Every birthday, he plants a tree in garden at home in Goa.

You have always been on the other side of the Hot Seat. How does it feel to be the one on the hot seat?
It feels uncomfortable! I wish it to be on record that this interview happened even after a lot of violent protests from me, and the only reason I acquiesced was, till now no one has refused to do an interview for Pulse. Nevertheless, I got a wonderful gift from my beloved team on my 2nd anniversary at IIPL!
One thing that struck me during this interview was, how difficult it is to answer seemingly easy questions like "what are your favourites"… There have been quite a few realizations about the questions we ask!

How has been experience at Pulse?
Some of my most enjoyable moments at IIPL have been time spent for Pulse. Here is an incident I wish to share with you all, and you can judge what kind of “celebrity” status I have... One of the contributors to Pulse wanted to make some changes in her article. I sent her a mail inquiring if she was done with the changes, and then, decided to follow up personally. Just as I was about to speak to her, she said, "Hold on! I have just received a mail from Editor of Pulse which I must answer right now. Then I will talk to you." I waited patiently as she typed and sent a lengthy reply to my mail; and only then calmly informed that I was the chap who had sent the mail.

The collaborative thought and effort that goes into shaping each edition of Pulse is truly something to be experienced! I take this opportunity to express my appreciation for all those with whom I have worked with during the last two years.

Gates shut down on Microsoft...

2008-06-27T06:50:00.000-07:00

Today, Bill Gates retires from an active role at Microsoft, the company he founded in 1975 with his friend Paul Allen. In a well-thought out and efficiently executed transition plan that spanned two years since June 25, 2006, Steve Ballmer continues as Microsoft CEO, while and Ray Ozzie and Craig Mundie would step in Gates’ shoes as Chief Software Architect and Chief Research & Strategy Officer, respectively. Gates would continue to be the Microsoft Chairman and its single largest shareholder; and he will also closely monitor a few big projects including the release of next operating system (Windows 7). However, he would cease to be the public face of the software colossus.

And that means a lot.

For the last three decades, Bill Gates has been the iconic figure of PC software industry; indeed he created the PC software industry. At a time when nobody knew what software exactly meant, Gates and Allen dreamt of a computer on every desk and Microsoft software in every computer.

But Gates wasn't just content with being a visionary; he decided to be the driving force in making this vision a reality. He brought to Microsoft ( and to the software industry at large) a hyper-competitive culture, one in which he often defined the rules of the games and sometimes broke them too.

30 years on, Microsoft continues to be the market leader in personal computer software, with its Windows operating system and Office productivity tools running on a billion computers worldwide, thus giving it a monopolistic market share of more than 90%.

Microsoft's phenomenal success hasn't hurt Gates. He has topped Forbes list of world's richest persons from 1995 through to 2007.

With great success comes great responsibility, and even greater criticism. A consortium of business rivals commonly known as NIOS (for Netscape, IBM, Oracle and Sun) is busy thinking up new ways to keep the rampaging Microsoft from exploiting its dominant position in desktop computing. Gates himself has been favourite punching bag of a number of groups, foremost among them the open source enthusiasts. He's often been maligned as a demonic figure, out to dominate the world. Gates has rarely responded to such personal attacks, instead focusing his energies in wiping out the competition.

On a personal level, Bill Gates has been my icon. Reading "Bill Gates & Microsoft" by David Marshall got me hooked to computers. Over the years, I have admired Gates for his sharp intellect, energetic drive and intense passion for everything he gets involved in. He has made nerds respectable.

He has also handled his immense wealth responsibly. Post-Microsoft, he would be active full-time at Bill & Melinda Gates Foundation. With $32 billion from Bill Gates and equal amount from his friend Warren Buffet, it is today the world's wealthiest charitable trust, with primary focus on eradication of extreme poverty, lack of education and poor health standards across the globe. It remains for us to see how Bill Gates employs his formidable intelligence and immense wealth to fight these fearsome foes of humanity.

I also hope that he begins a blog of his own.

Here are some interesting links related to Bill G.

Microsoft: Bill Gates executive page
TIME 100: Article on Bill Gates
TIME: In Search of the Real Bill Gates
TIME: Bill goes back to school (highly recommended)
Seattle Times: Bill Gates interview
Fortune: How I Work - Bill Gates
Joel on Software: My First BillG Review
YouTube: Harvard speech (Parts 1 & 2)

Bill Gates on 20/20 (Parts 1 & 2)

A Document Patch A Day

2008-05-11T08:30:00.000-07:00

When I began with technical writing, my preferred approach was top-down, which is, beginning every document with title, introduction, and then working my way towards the end of it.

At Infospectrum, the company I work for, we use Microsoft Visual SourceSafe and Digite for source control of code as well as documents. I have been a heavy user of both these tools, checking in and checking out documents for every paragraph added and every minor correction made, sometimes a dozen times a day.

Very soon, realization dawned that people do not need documents that much frequently, but when they do need it, they want it complete.

Then I happened to read Mr. Didier Thizy’s blog. In one of his posts, he puts forward the idea of “A Software Patch per day”.

He writes...
-------------------------------------
…. the source control must always be 100% functional. A customer request for a working version of the code, a tester's request for a last minute bug fix, a request to release an application update could come at any moment. Team members must always have access to the latest copy of working code. Nightly automated unit tests must all pass on the integration server. If the utmost quality in the source control is not preserved, then it becomes a bottleneck.
---------------------------------------
This hit the nerve exactly. So I read on…
----------------------------------------

Once you start development, I said, we have a requirement that you must submit "1 patch a day".
…

Submitting a small patch every day has several advantages:

Small patches are easy to understand, so you'll increase the changes of getting a quality code review (if you dump a huge amount of code, the reviewer may miss things or worse, skip the review altogether)

Frequent patches mean that problems will be caught early, before the developer goes too far in the wrong direction. This is especially important when your team is made up of team members in different time zones.
------------------------------------------

That got me thinking on how this concept could be customized for documentation. Here is a new process I have begun to adopt of late:

Now I adopt a Zoom-In approach: First create the whole document structure, complete with title page, headers, footers, logo and copyrights, revision history, followed by all the chapter titles and major sub-topics. In our project, we have developed templates for all types of documents we would need, so preparing a document skeleton is quite a quick job.
Next, I mark all the headings and sub-headings as TBD (To Be Done).
Then I begin working on the contents; it could begin either with introduction or the procedures or screenshots, depending on the document.
Before leaving for the day, I check in the document, making sure that the sections I had been working on are complete. Others are left marked as TBD.
The next morning, I check out the document, and begin working on it.
Around noon, just before leaving for lunch, I check in the document.
After lunch, I might check out the same document again, or check out another one and proceed with my work.

The advantages of this practice are:

Those who need the latest documents (for example, QA Team requiring a test-cases document), can take the updated copy by using “Get Latest”.
Documents in the source control are “functional” at all the times, that is, even though they may not be complete, they can be reviewed or even delivered to client for the sections that are done.
Since the entire document structure is ready, it gives a better idea of work completed so far and the work to be done. This helps a lot in providing time estimates.
Since only a few sections are updated at a time, it facilitates document reviews.

I would like to know what you think about this approach and how it can be made better.

Tools of a Tech Writer – Part I

2008-05-05T08:55:00.000-07:00

In earlier posts, we saw the steps to become a technical writer and the traits required for this profession. Today, we shall see some of the tools that technical writers use in their work.

MS-Office:

Notwithstanding the criticism heaped at Microsoft’s products, MS-Office still continues to rule among the office productivity tools. You must have hands-on experience on all the products in Microsoft Office suite, and should a particularly exhaustive knowledge of MS-Word. This seems rather a basic requirement, but as you work with MS-Word, you would be amazed to find its various hidden functions and capabilities. We hardly use many of these features during our ordinary home or office use; but a tech writer must utilize all of them to come with well-formatted documents in a short time.

Apart from Word, another component of MS-Office that you need to be proficient in is, MS-Visio. Visio allows you to create flow-diagrams, sequence diagrams, network diagrams etc. Either you would be creating those entirely on your own, or you might have to edit/update the ones created by programmer and testers.
Currently, I am paying some attention to the MS-Publisher and trying to figure out how to use it.

Microsoft released Office 2007 last year; however most of the community still uses MS-Office 2003. The reason for the slow adoption for Office 2007 seems to the extensive reshuffling of the menus, thus causing the need for us to unlearn our current expertise and re-learn the Office 2007 system almost from scratch.
I am also planning to try out OpenOffice suite.

Adobe Acrobat:

Acrobat is required to convert documents into PDF form. Although I started with using the freeware tools such as PrimoPDF, very soon I realised their shortcomings. For a professional PDF document, Acrobat is highly necessary.

SnagIt:

This is a tool for screen-grabs. The Windows built-in functionality of Print Screen works fine for rudimentary screen-grabs, but when you are working on a large document involving lots of screen captures, it is better to use a professional tool such as SnagIt. It has a number of features that you can use to make your life easier.
Currently, I am also trying out FastStone and GIMP and both seem to be equally good.

RoboHelp:

RoboHelp is a help-authoring tool; this means that it enables you to create online help in various formats, such as Help files, Web Help, JavaHelp, etc. It is highly essential that you are able to exploit this application to its fullest.
RoboHelp comes with its own PDF tool, known as RoboPDF. Though not as feature-rich as Adobe’s Acrobat, the RoboPDF allows you to generate deliverable-quality PDF documents without having to invest into Acrobat.

FrameMaker:

You can make do with MS-Word for small and medium documentation projects, but when the documents under consideration are huge, spanning hundreds or even thousands of pages, MS-Word proves to be a nuisance. In such cases, FrameMaker is the tool to opt for.
Like RoboHelp, FrameMaker is an industry standard in help authoring, but unlike RoboHelp it is very robust and offers a wide variety of tools for documentation.

Adobe PhotoShop / CorelDraw:

Although not a strict requirement, a working knowledge of image processing applications will help you to create illustrations and graphics on the fly, without having to approach the Design team for small tasks.

These are the tools that I currently use on a regular basis. Not all documents require all these tools, and there are some documentation tasks that require more than those mentioned above. Currently I am upgrading my skill set and would write soon on the tools newly added to my repertoire.

Do not await the "Eureka!" moments

2007-09-29T15:00:00.000-07:00

At Infospectrum India, the company I work for, we publish a monthly newsletter titled "Pulse." As a member of editorial team, I often approach office colleagues for articles. Many of them are willing to contribute, but they also have a problem: “I just do not feel inspired!"

Well, as technical writers, we do not have this luxury to await the flashes of inspiration. There are deadline to meet, and work to be done. If you feel unable to begin a writing task, Here are a few tips to beat the same.

Begin writing.
A blank page or a piece of paper can be quite intimidating, esp. when you have pages and pages to be written. The best way to overcome this fear is to begin getting your thoughts on paper, without paying any attention to the sequence or formatting or any of the works. Just get cracking!
Get started with hard facts and figures.
If you are feeling low on creative ideas, skip the writing part for a while and focus on raw data: facts, numbers, tables, graphs, illustrations. Once you get these on paper, you will begin to have a sense of their arrangement and what needs to be written to explain them further. Soon you would a working document ready that only needs to be spiced up with some extra text here and there!
Adopt a recursive approach.
No matter how big or small a technical document is, it is impossible to come up with a final copy in one go. Hence, rather than labouring your way through each section and then dispatching the copy without re-working, have a rough draft ready as quickly as possible and then have multiple reviews to improve each section per iteration.
Plan ahead.
Start compiling all the necessary details well in advance. Screen-grabs, performance reports should be taken as and when possible. Even if the user interface changes later on, it is easier to modify images then to start afresh.
Keep thinking and keep notes.
Keep thinking about the work to be done all the while... while walking, traveling.. And have a pen and a piece of paper handy to note down any ideas that may spurt up.

Traits for a tech writer

2007-08-13T09:00:00.000-07:00

In an earlier post, we saw steps to become a tech writer. However, does that mean anyone can become a tech writer? The answer, in my opinion is No. This is like saying that any one with a voice can become a successful singer or any one who can draw can be a great artist. By following the steps mentioned earlier, you can indeed become a tech writer, but to be a good one, you need to have some traits. In this post, we shall discuss those.

Passion for reading: Before you write, you must read. Read voraciously, and extensively. This not only expands the vocabulary, but also widens the lines of thinking and expressing oneself. Reading should not be limited to technical books. Novels, Fiction, Non-fiction, sci-fi, biographies, everything needs to be part of your read-list.
Passion for writing: Tech writing involves a lot of writing (typing). If you are of the type who can talk a lot but just abhors getting your hands on a keyboard, well, think well before even venturing out into this field. For every single page of your final output, there are lots of discarded drafts, revisions, and changes.
Passion for communication: Tech writing forms a part of larger field... tech communication. To be a good tech writer, you need to be a good communicator. You need to be able to approach people and get the information from them in efficient and effortless manner. This doesn't mean that you have to be talkative or extrovert in nature. On the contrary, people who talk too much tend to put off the SMEs.
Passion for learning: You need to be on the top of every new wave that comes up in the field you are working in. Sometimes this can be very frustrating... just when you are done with Adobe Acrobat 6, the version 7 hits the stands. But it is fun, if you can enjoy the learning curve. Very often, the knowledge in one package is reusable in other one, and mostly so in newer versions of same application.
Ability to listen: we often take listening for granted. But the fact is, when we thin we are listening, we are actually busy forming our own replies and reactions to what the other person is saying. This often warps the information that is being passed on.
Ability to perform under pressure: Documentation comes towards the very end of Software Development Life Cycle. Deadline pressures and unreasonable timelines are a part and parcel of every tech writer's life. You need to be able to perform under stress, and deliver stuff that is accurate and easy to understand.
Ability to be a teacher: a tech writer’s primary job is to make nonprofessionals understand the application or technology that you are documenting. If you are not able to express yourself clearly and precisely, all the other qualities go vain. So, there has to be a teacher in you...

Use e-mail effectively

2007-06-25T21:00:00.000-07:00

As a technical author, you could be working in a small team of just a handful people, or a one that consists of fifty people spread over different geographical locations. Chances are, e-mail would be your de-facto communication medium. It is a powerful tool, and should be used properly to reap maximum benefit.
Here are some tips borne out of experience.

Learn the tool.
We hardly ever pay attention to various options provided by the e-mail service. A professional e-mail client has many features and options that we are not just aware of. Learn the e-mail application like any other software package.

Make your mail easier to read and act on.
Suppose you need to send a screenshot of an error message. Rather than attaching the image as a zip, insert it directly into the mail (unless of course the image size is prohibitively large), thus saving your recipient’s time and effort for downloading and unzipping the image

Follow the basic rules.
Run spell check after writing the mail. Read the mail before sending. Confirm the technical details. Ensure that you have included all the concerned people in the recipient list. Make sure the attachment (if any) is in place.
We know all this, don’t we? Yet how many times we find ourselves sending badly spelt mails to wrong persons without attaching the document on which we spent four hours?

Do more than just type.

Our instinct is to type out a mail, and shoot it off. Before you hit the “Send” button, pause a bit to think about what associated tasks you can do with it. You can set a reminder to yourself, or set a follow-up to the receiver, or make a note in calendar, or note down some details that would be useful later. In short, think beyond just writing and sending the e-mail.

Take each thread to its logical conclusion.
When you send a mail requesting for subject-details, make sure that you continue with the same thread till it has been resolved. This gives both the parties benefit of knowing what was discussed in the past, and helps in sorting the mails by subject-lines.

Use e-mail as a follow-up.

Rather than typing out 4-5 paragraphs explaining the background details about some query to be asked, it is preferable to go over and discuss the same in person. Later, you can simply write a mail that could start, “With reference to our discussion today, please provide following information..."

Use e-mail sparsely.
We tend to develop a habit of sending emails for petty matters that could easily be asked to the person sittting next to you.

Categorize smartly.

Very often, we end up asking for same information again and again because there is just no way to extract it from the thousands of mails in the mailbox. Setting up e-mail rules helps classify the incoming mail into folder that can be easily browsed or searched through.

Archive periodically.
Over a period, the e-mail client tends to be bogged down under its own weight. Archive mails on a periodic basis.

Do not send acknowledgement mails..

... unless you wish to add to the conversation. Instead, you can inform the sender over instant messenger (or when both of you happen to be at the coffee machine) that you received the mail and are working on it.

E-mail is a double-edged sword. Unless you gain control over it, it can make life more difficult for you!

Steps to become a technical author

2007-06-18T21:00:00.000-07:00

Well, it is barely a month since I started this blog, and I have already started receiving mails inquiring about technical writing. After replying to a couple of mails, I have decided to put up some general guidelines to those who wish to enter this exciting field.

First thing to decide is whether you wish to take up this profession as a full-fledged career or just a part-time hobby. Technical writing/documentation comes towards the end of software development life cycle and deadline pressures can be frustrating at times.
Make sure it is technical writing that you want to be in. There is a vast difference in writing an article in newspaper or a magazine and writing a user-manual. Tech writing allows very little scope for individual style and elaborate ‘build-up’ of a ‘story-line’.
Once it is clear that it is technical writing you have in mind, start with identifying a domain. Is there any specific area you would like to work in? Your academics should make this decision easy. Although technical writing in software is mainly highlighted, in reality it pervades all fields of knowledge: arts, science, literature, music, sports, etc.
Google for “technical writer” and related terms such as ‘technical author’, ‘technical writing’, ‘documentation’, etc. Wikipedia is a great place to start.
Begin sharpening your language skills. Pay attention to the way you translate your thoughts into words. Listen and read good quality English. Reader’s Digest and BBC are two excellent sources.
Buy selected books on tech writing. A good dictionary, a thesaurus is necessary. Some style guides, such as Apple Style Guide are available online for free download.
Be proficient in the software tools required in documentation. MS-Office and Adobe products such as RoboHelp, FrameMaker are the industry standards today.
Next obvious step is to join some online community, such as technical writer’s yahoo group, or an Orkut community of tech writers. Read the postings daily, get familiar with the jargon, and most importantly, start identifying with the process.
Browse through various types of technical writing: user manuals, instruction manuals, SOPs, etc. Note how the content is organized and presented.
Create a resume. Highlight the strong points related to your domain knowledge as well as writing, esp. if you have any contributions to college magazines or prizes in essay competition etc.
Talk to some established technical writers. Any company of some repute has at least one tech writer, so they shouldn’t be hard to find.
Having done your homework, start scouting for possibilities! Online groups, communities, and personal contacts mentioned above would come handy here.

Hope this helps. I have some recommendations about books, websites, and other reference material, which will be covered in a separate post.

Evolution, not revolution

2007-06-06T21:05:00.000-07:00

Every person has an individual style of performing work-related tasks. This is certainly an asset, but it can also turn out to be a liability because it leads to differences in look and feel of the final product. It is exactly for same reason that coding standards, testing standards and documentation standards have evolved.

In spite of all these processes in place, it is human tendency to go about making reforms. This can lead to clashes with other members of team as well as with the clients. Here are a few rules of thumb to be taken care of before modifying an existing template or documentation format:

Take time to study the existing documents before you start shooting suggestions to your right and left. There might be some particular reason to why this style is used. Ask about it.
If you are continuing a document in progress, which was initiated by someone else, it is a better idea to continue with same template for that particular document at least, unless you are ready to re-write the whole thing again.
Rather than converting an entire document into a new template, convert a section of it that covers all main aspects, and send it for review. This way, if it undergoes major changes or even if it is rejected right away, you would not have wasted too much of your time and efforts.
While suggesting a new style, justify why you think it scores over the old one.
Until the new format is approved, always maintain a copy in old template.
Give preference to functional changes, rather than just look and feel of the document. For example, you may try a different TOC style because it gives better access to the contents, rather experimenting with a different font just because it "looks better”.
Overseas clients mostly stress upon accuracy and consistency. Be sure you maintain these two aspects while migrating over to a different format.

This does not mean that change should not occur. The point is: it should be gradual and approved by all stakeholders to avoid rude shocks at the last minute.

From Coding to Writing...

2007-05-29T09:00:00.000-07:00

Hi,
Let us start ByteSpace with some background information about myself. I am Gautam aka Raghunath Soman, currently 26 years young, and I hail from the beautiful state of Goa in India. A graduate in Industrial Chemistry, I did GNIIT course and began working as Dot Net programmer at a start-up firm in Pune. After coding for about six months, pangs of self-doubt gripped me: Was I happy with my work? Was I doing justice to my strengths? Did I want to be doing this five years from now?

It didn't take me long to find the answers: No, I wasn't happy being a programmer, and I didn’t want to do coding throughout my life.

This led to the next obvious question: If not programming, then what?

Since schooldays I have been an avid reader and a compulsive writer. I enjoy science, computers are my passion, and I love literature.... Was there any profession that would do justice to these qualities?

I vividly remember the moment when the answer hit me like lightening from the sky. Buddha must have felt same on achieving enlightenment.

Technical writing was where I had to be.

Without wasting time I consulted with the few people I considered as my guiding beacons... Tushar & Rahul. Both of them un-hesitatingly approved of this idea, and gave me confidence that I had the basic qualities necessary for a career in technical writing.

A couple of months into background study, and I got an opportunity to make the actual career-switch, thanks to Tushar. I joined Infospectrum India a year ago, and have been working in Marine domain since then. The journey so far as been extremely good. Since I didn’t have any prior experience, it has all been learning-on-the-job.

To be doing something that you are passionate about and getting paid for it... what could be better than this!

Welcome to ByteSpace

2007-05-25T20:30:00.000-07:00

Hi All,

I have just created my blog: ByteSpace. This would be a professional blog, dedicated towards my passion and my work.... technical communication.

A new journey has begun... I seek your wishes and companionship to make it exciting....

Regards,
-Gautam Soman.

25th May 2007.