By, Anagha Walvekar
If you are new to the profession of technical writing, this article is for you. Here are some tips to help you sail smoothly as an Information Developer. Yes, it’s good if you have completed a course in technical writing; but that alone won’t take you far. Your litmus test starts when you get your hands dirty on the job.
- Get a Guru: While growing up, we pick our role models. So is the case with our profession. Find senior members in your team you can look up to. Sometimes your organization may make that decision for you. If not, you pick your ‘Guru’ and let them guide you through the process. Seniors in a team are equipped with the knowledge of the product, process, tools, and team dynamics. You can ask their help to sail through a situation.
- Ask, ask, and ask: Whoever said “Ask and it will be given to you, seek and you shall find” was right! When in doubt, ask. When concepts are not clear, ask. When you think you need more time to complete something, ask! Your managers and leads can help you only when they know what you are going through. So do not hesitate to ask. First, do an extensive research. Jot down the questions that pop up in your mind when you are reading a concept for the first time. Try to seek the answers, but if you are not convinced with your findings, ask with confidence.
- Understand the process: Although the process of writing technical documents is more or less the same in every organization, you must know the exact process followed in your organization. It is a common practice in organizations to document all the processes that are followed by various teams and the information will be accessible to you. Read it and try to imbibe it. Bookmark it for quick reference and easy access.
- Learn the writing style: Most organizations follow one or the other style guide, such as the MSTP or IBM style of documentation. You must know the style of documentation followed in your organization.
- Read the existing documentation: Well, they say nobody reads the documents. Be the trendsetter and change that ☺. Start by reading the existing documentation. It gives you a good idea of the writing style used in your organization. If your organization has multiple products, it is a good idea to find out about the domain you will be working in. Familiarize yourself with the terminology and the style of writing.
- Get to know the product: After you have been assigned a product, install the latest version of the product on your computer. Play around with it and verify whether you can complete a task by using the existing documentation. This will help you identify any defects in the guide as well as in the task at hand.
- Develop a good rapport with the team: When you do your homework, install the product, and use the feature that needs to be documented, you gain some credibility with your Engineering team. This is how you start developing a rapport with them. They need to see that you are serious about learning and that you understand what they say. Also, have a regular interaction with your manager or your team lead. Discuss your challenges and things that you might want to do differently.
- Attend all the team meetings: You can remain updated on the development of the product by attending all the team meetings with the Engineering teams. When you attend these meetings, sometimes you get to know the ripple effect a feature can have on other guides. You get a holistic picture when you hear from everybody in the team and this can help improve your documents.
- Acquaint yourself with the documentation tools: When you are new to the team, you might not be familiar with all the tools used by the documentation team. However, as and when the time permits, get trained in all the tools that are used and are available. Master at least one text editing tool and one graphic editing tool.
- Review your work: Introspection is the name of the game ☺. Sometimes, it pays to be self-critical. After writing a draft, keep it away. Don’t look at it or review it just yet. Give it a cooling period of at least four hours. Now is a good time to wear your ‘self-deprecating’ hat. Try to be harsh on your work and find faults with it. Find as many mistakes as possible in terms of the writing style, grammar, technical accuracy, and format. Only when you are happy with all the aspects, should you send it for a review.
- Create checklists: It is ideal to have the following checklists:
- A product checklist to cover the points discussed with your team and the accuracy of the tasks mentioned in there
- A checklist to adhere to the writing style guide
- An element checklist if you are on DITA
- A grammar checklist that specifically looks for grammatical mistakes
- Stay focused and meet the deadlines: It is essential to stay focused on your tasks and deliver quality work on time.
- Focus on continual growth: Attend as many sessions and conferences related to technical communication. Maintain a blog. Follow blogs of other writers. Stay up to date with the latest trends and innovate at work.
- Be happy, think positively, and keep the right attitude: A wise person once said that give your reviewers a plain paper and they will still have comments on how to make it better! So, do not let anything bog you down. Try not to repeat an old mistake, at the same time feel free to make new ones. How will you learn otherwise? Mistakes make you wiser ☺. Have the right attitude and you will learn along the way. At any point in time, it is important that you stay positive and enjoy what you are doing.
About the Author
Anagha has over 14 years of experience as a trainer. She has also authored courseware for C and C++ programming languages. She has done English language reviews for “Employability Enhancement” (E2 series), a series of books published by Avani Publications, Pune. Currently, she is working as an Associate Technical Writer with TIBCO.