Write It Right: A Guide for Both Novice and Seasoned Technical Writers

Hello, I am Khyati Karki , a seasoned Technical Writer with 12+ years' experience. Besides crafting manuals and notes, I've explored roles like Internal Communication Specialist, Trainer, eLearning Designer, and Technical Copywriter. As an Information Architect, I managed teams, set procedures, and built a vast document, training, and video repository. Excited to share insights into the technical writing landscape!

This blog is for all Technical Writers- newbie or tenured, aspiring to lead a team or work as individual contributors or part of a team of technical writers. So, let's dive in.

1: Product Knowledge

Spend a good amount of time in understanding the Product/Application. You may receive product training. If not, meet your colleagues and learn the product.

🤔Dig deep into the organization's websites' resources and even the news pages. Audience understanding determines 50% of your aims.

Albert Einstein most famously said “If you can't explain it to a six-year-old, you don't understand it yourself.”

2: Understand the Organization's Hierarchy

🤝Meet the engineering staff you'll work with often. First impressions might not last, but they matter. A meet-and-greet meeting with your team and manager always helps. You should know all major stakeholders, including Senior Management (approval board), IT, and even the administration, in the first two weeks.

It's more than documents; it's your roadmap to success.🚀

3: Understand the Purpose and Audience

🎯Before starting, understand the purpose of the document even if you've been through it in your initial meetings with the manager or teams. It's essential to know the goals of the documentation and the target audience. This will help you tailor your writing to meet their needs and expectations. 🧵

🎭Be flexible—adapt your writing style to exceed expectations.

4: Documentation Planning & Roadmap

Arrange Meetings and Define Tasks: If there is no documentation available, start by arranging meetings with engineers or managers to define the application or your first task, such as a use case or case study. Ask them what they would want their audience to know if they had to write about the product. This approach works well for blogs, case studies, and use cases, mostly written by technology copywriters/content writers.

You can follow an example of a well established product, such as Microsoft Azure Boards (Project Management platform). See how they start with what the product is, how to get started, and then jump to the features and functions. Some applications will have features based on roles, so define the roles before diving into the functions of a feature.

Now you are ready to dive into your first project! Remember, it's not just about ticking off tasks; it's about making life easier for everyone. Follow these quick steps:

1. Smart Meeting Setup:

   • 🗓️Schedule a meeting to grasp the project's roadmap.

   • 📝Equip yourself: notepad, check. Recording with consent, check.

2. Understanding Agile:

   • 🔄Think Agile methodologies—Work in phases, work in Sprints

   • 🛣️ Your job? Sync up with the plan and create a clear documentation roadmap.

🕰️Before setting expectations, invest time in acquainting yourself with both product and tools.

5: Using Appropriate Tools and Resources

MS Word is like the old reliable friend good for certain missions. But for a broader perspective, peek into Adobe FrameMaker and MadCap Flare. If your team doesn't use structured authoring, consider creating templates for future ease. Both these products have extensive resources available, which will help you understand and start with a basic documentation. My suggestion would be to create a template in the tool if structured authoring does not exist. This will save you a lot of time ⏳ in the future.

Another great tool for creating a cloud-based Knowledge Base is Document360. This is a great tool for creating a public or private audience-based documentation. Extremely easy to use, a little expensive if your documentation is very large (additional cloud space charges), but comes with a great support team, including easy "how-to-use" guides and videos. Another honorable mention is Confluence.

Last but not least, continuously improve the documentation.