Vinish Garg

Technical Writer. Published Author. http://www.vhite.com

Posts Tagged ‘Technical Writing

Ready for STC Annual Conference Next Week

leave a comment »

Finally, we have the countdown to STC India Annual Conference 2010. I had a quick recap today on conference agenda, and the venue: Hotel Sheraton New Delhi. Please see: http://www.itcwelcomgroup.in/Hotels/sheratonnewdelhi.aspx for more details on conference venue.

Written by Vinish Garg

November 7, 2010 at 8:02 pm

“Technical Writing” moving to a different space

leave a comment »

06 November 2010

This space https://vinishgrg.wordpress.com has been a platform where I have talked about technical writing, cricket, movies, liesure and friends, and ‘we, the people’. However, I realise that ‘technical writing’ needs its own independent space.

So, I am moving all (past) posts related to ‘Technical Writing” to a new space at: http://www.enjoytechnicalwriting.com. From now on, all ‘technical writing’ posts will be available at this new space. However, I shall continue to use *this* space for everything else.

Best Regards
Vinish Garg

Written by Vinish Garg

November 6, 2010 at 7:40 pm

Reviewing a Technical Document

with 3 comments

While training new technical writers, many organizations focus their training efforts on ‘Developing’ the documentation which is primarily about writing procedures, topics and instructions. The writers are also introduced to documentation process, style guides and templates but I have realised that organizations do not have detailed plans to train on ‘How to Review Documentation’.

Reviewing is as important as writing and I always emphasize that reviewing skills are as important as documentation skills. For less experienced tech writers in my team, I tell them to revise the User Guides multiple times, for:

– completeness (are all features covered/explained?)

– UI texts (are all UI texts such as fields, buttons and tabs correctly referred to in the document?)

– graphics (does the text on images make sense?)

– clarity of language (are instructions clear?)

– correctness of language (is the language correct for tense, punctuation, sentence structure, grammar, and other paramters of TW?)

– accuracy of instructions (no stories and no emotional connection, ensure conciseness and ‘problem resolution’ aspects of procedures and instructions)

– additional elements (notes, cautions, confirmation messages)

– consistency (adherence to style guide, conventions )

– template (layout for space, margins, style guide and conventions which includes typography, colors and icons)

– TOC (logical, complete)

– cross-references

– index (accurate, comprehensive)

– Others (document properties, disclaimers and copyrights, title page, headers and footers, date, version, author name)

– review complete package for everything

– review

– review

– And again Review 

A technical writer should always have a checklist for different aspects of document review.

Written by Vinish Garg

June 23, 2010 at 2:04 pm

Growing as Technical Writer

with 4 comments

Technical writers generally enjoy their day-to-day tasks whether it is developing documentation prototype, writing instructions, reviewing a document (of self or others), or planning for a document publishing or release. My experience suggests that technical writers are so used to ‘feel-good’ factor that sometimes, the less experienced technical writers are ill-prepared to handle issues, conflicts, and question marks. Even if somewhere internally, they agree that ‘the change’ is in the interest of project, they are not ready for this “change”, when things are difficult. Beginners may respond differently, but they tend to follow how others ‘respond’ in that work culture. And it is an unwelcome sign.

I keep on emphasizing that it is very important to have a sound platform, and to understand technical writing in wider perspective rather than considering it as job of merely writing instructions for user manual. It does not call for a complete personality makeover (neither I encourage it nor it is required); however, individuals need to work on their thought process. Some useful points for growing into a good technical writer are:

  • Writers’ block – Treat it.
  • Understand the pulse of your project team.
  • Know your ability.
  • Smile. Your reviewer’s job is to find mistakes in your document.
  • Agree to disagree.
  • The smallest mistake can cause the biggest escalation.
  • There is no such thing as a perfect document (almost).
  • Love your document till you send it out.
  • Always Zero-in your focus on customer requirement and the basic objective of document.
  • Keep it Simple.
  • Always follow the style guide.
  • Be consistent in your thinking, planning and writing.

I recall that I read a few of these points somewhere. If anybody can help me connect to that, I would love to give credit to that source and person. Happy Writing!

Written by Vinish Garg

June 7, 2010 at 11:15 am

Technical Writing is Different from Other Positions in IT

with 4 comments

How it is different from other jobs in IT (development or QA)

  • There are no automated or pre-defined parameters to test your documentation. Developers can run their code and see if it is fine, test engineers can run scripts and map their test cases against the system functioning. However as a technical writer, you CANNOT verify your document against a pre-defined set of parameters’ to see if it is correct. You use your experience. Of course there are facilitators such as Style Guide, Templates and Process, but it all comes to your experience and writing skills. There is no way you can have a system that ensures that the language is correct and meets its objective.  Does it mean that you are at a disadvantage? Certainly Not!
  • In development, a software engineer who has developed many ecommerce sites and Facebook applications can feel frustrated or stagnated if one continues to get same kind of product development tasks, or to fix bugs in same or similar products (of course exceptions are there). In technical writing, you are constantly doing something new. Even if it is same product, you get to write fresh instructions. Some procedures are always new and at least you write new sentences. You do not have a for loop or a once-written login module that you can use in every document (like many developers do). You have the scope to be creative, within the parameters. And you get to learn and update yourself on new technologies just as other professionals.
  • A technical writer works with astonishing attention to details. You cannot afford to miss a full-stop even in a 140 page manual; it is a crime. It is a huge satisfaction when you tell your documentation manager that the document is complete IN ALL RESPECTS.
  • Research suggests that technical writers are generally more satisfied and enjoy greater job satisfaction as compared to professionals in development, QA or UI design.

Where it is REALLY DIFFERENT!

  • Technical writing is quite an individualistic job, and every individual thinks differently. No two individuals can write a procedure or a paragraph in exactly the same manner. So while working in a team, one needs to agree somewhere that they are not doing documentation for themselves. Rather, they are doing it for the business, and then the organization whom they work for. When I compare it to development, there is a difference. To write code of a feature, there can be one particular way where different team members can agree that this is the best (most effective or optimal) way to do it. This is not always true in technical writing. You can think why not the way ‘I write it’ when there is nothing wrong in it? This is a dangerous sign if the individuals fails to realise that somewhere, they all need to agree on ‘how to write’.
  • When a Documentation Manager reviews a document, the original writer who wrote instructions should:
    • Understand that sometimes there is no reason or justification of ‘why this way’ because there are no definite answers. The most valid answer is ‘this is so’ because ‘this is how we do it here’.
    • Understand that the comments are not to highlight writer’s mistakes. The comments are for the ‘document’ and not the ‘writer’, so writer should not take it personally. Many newbie’s find it difficult to accept comments because they think that they are right (or that they are not wrong). But when they revisit these situations after 2-3 years of experience, they laugh at themselves, they have learnt many valuable lessons the hard way.

The career graph is upwards for experienced as well as for newbie’s. The demand for good technical writers is increasing and is expected to increase in next few years. However, it also calls for diversified skills in tools and deliverables.

Written by Vinish Garg

April 13, 2010 at 2:41 pm

How much I miss STC events

with 3 comments

As always, I registered myself for the New Delhi STC Session for 21 March, and as always, I missed it. On 20th evening, I packed my stuff and had my dinner early. This ensured that I could sleep early because I needed to travel 300 km before next morning. The next moment I heard thunderstorm and saw that it was raining cats and dogs :(.

I cursed the fate as night travelling in heavy rains was not really a good option. For next few hours, I dreamt of DITA (the subject of discussion) and oh… I missed it. It had happened earlier too, I would register and could not make it for some reasons. How much I miss STC in this sleepy (sleepy for technical writers) but othrwise beautiful city :(.

And as always, I vow to be there next time – Come What May (Probably it would be in MAY:) ). God Help me please.

Written by Vinish Garg

March 23, 2009 at 9:49 am

This too is Writer’s Mental Block

leave a comment »

The last week has been one of the most amazing in my professional life – exciting and disappointing at the same time.

I had my first release of documentation suite scheduled for release – where I had worked independently and was solely responsible for its successful external release. At the same time, I deparately wanted to be part of STC’s annual conference in PUNE.

The tussle between joy and agony continued 24X7….

When I saw my documents finally published on intranet and extranet today, the smile widened but soon it vanished. I saw that the conference photogaphs were uploaded on STC official site and God – how badly I missed being a part of it :(.

Har kisi ko mukkammal jahan nahi milta…!
kahin zameen to kahin aasmaan nai milta…!!

I wonder how I should reflect at that week now…

Written by Vinish Garg

December 15, 2008 at 2:49 pm

Posted in STC, Technical Writing

Tagged with ,

%d bloggers like this: