Posts Tagged ‘Technical Writing’
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.
06 November 2010
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:
. 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.
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)
- index (accurate, comprehensive)
- Others (document properties, disclaimers and copyrights, title page, headers and footers, date, version, author name)
- review complete package for everything
- And again Review
A technical writer should always have a checklist for different aspects of document review.
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!
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.
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.
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…
I recently started using Arbortext Editor (5.2) and I am terribly stuck.
I am working on a root document (combination of Ref Guide, Quick Guide and Online Help). Take an example where I have a task with a title as ‘Sending Invoice to Archives’. It has its corresponding xref as ‘AF.Admin.Sending.invoice.to.archives’, and I see a corresponding file entity (XML) with name AF.Admin.Sending.invoice.to.archives’ and an HTML as well with name ‘AF.Admin.Sending.Invoice.To.Archives’.
When I need to update the title as ‘Sending Invoice to Personal Archives’, how do I do that? I guess I MUST NOT EDIT THE ATTRIBUTES of existing xref as it is linked to many titles/tasks/topics in the documents. Should I create a new xref for this updated heading? And how do I handle existing HTML, should I change its attribute? This is really confusing. I tried but it was messed up.
Please HELP ME, and TONS OF THANKS in advance.
|The first few months at first job as technical writer are confusing since you are not always sure what exactly you are supposed to do. Your role is less significant in the company; not all information regarding the project is communicated to you, and you rarely sit late nights or miss your lunch.|
|It is only after about a few months of experience, when you have developed at least a couple of documents that you begin to understand the finer points of technical writing. Once you know your job, and are comfortable doing it, it gets extremely important to raise the bar.|
|This is the time when you should learn the difference between a poor document, an acceptable document and a good document, and make required improvements.|
|Have a look at an example of poor documentation.|
|This is an example of poor documentation because of following reasons.|
|Rectangles in Red color: The space between image and text is inconsistent. It looks as if the image is centrally aligned in a specific area for all three points. One, a centrally aligned image does not look good since the paragraph starts at different positions wrt left alignment. Two, it leaves the space between image and text as unequal.|
|Circles in Green color: The points in list terminate inconsistently. One of the points does not end with a full stop, while others do.|
|Circle in Blue color: There is double space between the two words. A technical writer should take not more than 20 seconds to point out if there is a double space anywhere in one page of a document.|
|Circle in Yellow color: The word the is used unnecessarily, at many places. Though the use of the is very tempting, it is generally not required most of the times.|
|Circle in Brown color: A technical writer must avoid the continuous form of verb such as clicking. A user control such as a button does not allow a user to do something. Use enables rather than allows. Use words that are devoid of feelings. For example, use required, and not desired.|
STC Learning Session on June 28, 2008 @ Chandigarh
The India chapter of the Society for Technical Communication is pleased to announce the first learning session for technical communicators on June 28, 2008 @ Chandigarh.
To know more about STC India, please visit www.stc-india.org
10.00 AM to 10:30 AM
Registration and Introduction
10:30 AM to 11:30 AM
Session 1: “Blogs, RSS and Folksonomies: An Introduction to Web 2.0″ by Saravanan Manoharan from MTree Software
About the session
In this session you can get to know the basics of Web 2.0 and its relevance in Technical Communication.
You can also get some insights on:
* Blogs – How to create a company blog in five easy steps
* RSS – How to use RSS in your blogs
* Folksonomies – How to use Folksonomies effectively
Saravanan Manoharan is a Computer Science graduate, currently working with Mtree Software as a Technical Writer. He has around six years of experience in Technical Communication. Saravanan is also pursuing the PGPBM for Working Managers (WMP) course conducted by IIM Lucknow, Noida Campus. His hobbies include networking, playing drums, learning new languages, playing all sort of sports, and reading varieties of books.
11.30 AM to 11.45 AM
11.45 AM to 12.45 PM
Session 2: Session on “Teaching Technical Writing” by Amit Das from Chitkara University, Chandigarh
About the session
In this session, Amit would be discussing the following:
* Technical Writing: Perception and Challenges
* Technical Writing Process
* Resources available for Technical Writers
* Growth in Technical Writing
Amit would also be informing the audience about the latest Technical Writing books that are available and at the end he would like to discuss with the audience and get inputs for an ideal Technical Writing Syllabus.
Amit Das works as a Senior Lecturer in Chitkara Engineering College, Chandigarh. He is a Post Graduate in English, ELC and has a certificate in Documentation. He has varied experiences starting from working in an NGO to Documentation Manager. Currently, Amit is teaching Technical Writing and College Writing for George Brown College, Toronto in Chitkara Engineering College, Chandigarh
12.45 PM to 01.00 PM
Q&A and Closure
Seasia Consulting is sponsoring their venue for the First STC Chandigarh Learning session on June 28, 2008.
Seasia is one of the fastest growing IT services companies in the Chandigarh region. Seasia exclusively provides offshore development services to Saber Corporation, Portland, USA (www.sabercorp.com). In their work together, Saber and Seasia have demonstrated their close alignment in their values, work ethics and passion for excellence. Saber’s corporate mission is brief and straightforward — “To be the premier provider of software products and services that enable government to better serve citizens.” Saber’s demand for excellence coupled with Seasia’s capability and resourcefulness have combined to help Saber fulfill its commitments to its customers. Saber’s incredible growth rates also create a high rate of growth for Seasia as well as provides employees of Seasia with both temporary and long term career paths into Saber in the US.
For more details about Seasia, please visit
SCO 40,41,42, Sector-26
Chandigarh – 160019
Phone #: +91-172-5056600
How to get to the venue
Please refer the map here:
Maximum Number of Participants:
This session is limited to 30 participants only.
To confirm your participation, please send your contact details (Name of the Company and Contact Number) to Saravanan Manoharan at firstname.lastname@example.org and cc to Vinish Garg at email@example.com
Please do not inquire about the session on this mailing list. Your participation is confirmed only if you receive a confirmation mail from Vinish Garg or Saravanan Manoharan.
Rs. 150.00 for non-STC members. Free for STC members (Please quote your STC membership ID while sending the mail).
Please note the following:
- All participants (STC members or Non-STC members) must register and get a confirmation mail from Vinish Garg or Saravanan Manoharan on or before June 25, 2008.
- Non-STC members can pay the participation fee at the session.
Thanks and Regards
STC India Chapter
More details are available at: