Lessons From My Two Years as a Technical Writer

9 min readJun 17, 2023

Technical writers are a unique type of tech unicorn.

In 2021, I joined Wizeline’s technical writing team, the largest of its kind in Mexico. Around 40 writers from all backgrounds and various skill sets have two main things in common: a passion for writing and familiarity with technology and coding.

It is always challenging to effectively summarize an experience that is so broad and goes so deep, but I will share my perspective on being a technical writer. This may be your sign to switch careers and join the wonderful world of documentarians.

· What Is Technical Writing?
· TW Is Not a College Program, and Mentoring Is Key
· Writing Is More Than Following a Style Guide
∘ Tools and Strategies
∘ Common Traits
· No Writer Is an Island
· Once a Tech Writer, Always Tech Writer
· AI Can’t Replace You
· Secret Survival Skills
· Resources

What Is Technical Writing?

In the simplest way, tech writing is behind our ability to effectively use a tool, maintain and enhance a code base, and communicate with end users.

A tech writer is responsible for creating that amazing API documentation that made the difference between a successful implementation and not knowing what to do.

“Technical writing is a continuous process of learning, carefully gathering, sifting, organizing, and assessing, all while trying to craft something that makes sense for a user.” — Krista Van Laan

Tech writers have a process that enables them to do the following:

Understand a project/product in a general way.
Understand a project/product in a specific and technical way.
Propose a set of documents that best support the project/product.
Execute the documentation strategy.

These documents include API references, developer’s guides, administration manuals, user guides, DevOps guides, and many others. Every piece of documentation has a specific purpose and an intended audience.

To achieve this, tech writers must constantly learn new things and become experts that guide developers and end users to enhance their experience with tools and products.

TW Is Not a College Program, and Mentoring Is Key

Few schools offer a technical writing degree. You don’t usually go to school to become a tech writer. You have key skills and knowledge that align with the discipline.

In this context, having an experienced mentor makes all the difference. And after you become comfortable with your craft, become a mentor yourself. You’ll find that community and teamwork make tech writers stronger.

Find online communities and support if you are part of a smaller operation. Trust me; you can’t improve if you do it on your own. Feedback and challenges are essential parts of a successful career.

In short, you become good by creating documents and receiving objective feedback. You become an expert by learning and applying best practices and then teaching them to others.

Writing Is More Than Following a Style Guide

You can learn to follow a style guide, but experienced writers have the intuition and skill to develop ideas.

Not everyone will agree, but writing in an effective way is much more than learning the rules. Much like singing and dancing, you must have a feel for it, talent, some say.

Most of us come from a general writing background, from science fiction to poems, to blogs. We’ve always done it out of inspiration rather than having to. But passion is not enough; specific tools and strategies help us complete quality work, and I’ve seen some common traits among my peers.

Tools and Strategies

Yes, we have a weird love for grammar, but no one is perfect. We implement tools like spell checkers and style guides to support our process. Following rules gives us two main things: quality documents and a standardized voice. In technical writing, you don’t need texts with a quirky personal touch, only information as precise and accessible as possible.

Having a note system to organize ideas and create content from them is valuable. Make recordings of your interactions with developers and other team members whenever possible. Then, use those recordings to write detailed documentation.

Ensure to know Markdown and how to implement static site generators. You’ll be amazed at how much value you can create for a customer or team by designing a solution that best adapts to their needs.

Keep in mind that tech writing does not have a universal solution but a universal workflow. No matter the challenge, if you base your work on the following steps, you are on the right track:

Research: The research phase enables you to understand the challenge and its context and begin exploring possible documentation needs.
Get to know your stakeholders: No matter the project, you are part of a team. You’ll have customers, teammates, and possibly other parties invested in the success of the overall strategy. Get to know them, conduct interviews to collect feedback and thoughts on what kind of documentation they expect to see, and propose things based on your experience. These interactions strengthen the collaboration and create a sense of trust between you and your stakeholders.
Identify your audiences: Use this stage to identify, based on the specific product, who needs support, either using it or creating and maintaining it. Those are your audiences, and they have particular needs.
Create a documentation plan: After researching, gathering feedback, and identifying your audiences, design a plan that best serves all involved parties. Specify each document with its purpose and audience, and estimate the timeline and activities that will enable you to complete them.
Communicate your plan and have an agreement: Ensure to communicate your documentation plan in a formal manner. It could be a document shared with key stakeholders or an activity plan that is easy to understand and execute. Gather and integrate feedback before finalizing your strategy.
Execute your documentation plan: Prioritize tasks based on the development flow. Coordinate with team members to collect all relevant information and stay in the loop to know how and when things change or advance.
Establish peer review rounds: Gather feedback from other writers and subject matter experts. Know that you are not your work and that everyone makes mistakes. The important thing is that this is the best opportunity to learn and improve.
Estimate feedback integration times: After peer review rounds, you’ll need time to integrate the feedback and create a final, improved version of your document. Ensure to consider this time in your activity plan. If you are working with an agile framework such as SCRUM, assign points to this task.
Deliver the documentation following the agreed format: After the documentation is ready, deliver it according to a previously agreed format so that the content and this format adapt to the intended audience. A developer may prefer to see the documentation within a repository. At the same time, an end user may benefit from having it available through a UI or even a PDF file they can easily download.

Common Traits

As mentioned before, the tech writer’s profile definition is tricky. However, I identified some common traits among my peers that are not only part of their personality but also acquired through their experience.

Curiosity: We are curious cats. We feel the need to understand things, learn things, and inquire about specifics that other team members don’t even think about. I used to work with a solutions architect that said I was like the team’s Sherlock Holmes.
Organization: An organized writer is a successful writer. The trick is not only to gather information and do our research. We also have effective ways to organize our findings so that the writing process has a proper flow and we don’t miss important details.
Attention to detail: A good writer is its own best critic. We tend to obsess over how we present ideas, constantly asking ourselves if they are clear enough, well organized, appropriate for the audience, and many other things. To be honest, every typo that goes to a peer review hurts us a little.
Tech savviness: We are comfortable with computers and cloud technologies, reading basic code, running database UIs, and using entity-relationship diagrams. Much like a Swiss knife, we adapt to all tech stacks to understand implementations and create architecture diagrams. We review CI/CD strategies and DevOps infrastructures to develop guides and present this information to various levels of detail for different audiences.
Grammar police: I mentioned it before, but we have a weird love and passion for grammar. Additionally, by providing peer reviews, we become more effective at identifying errors and sharing ideas to improve texts. I may be lucky to have been part of a kind and supportive team, but this practice is never out of a superiority complex. It is always from a place of mentoring and helping others.
Reader advocacy: You get to a point where no matter what you are writing, you try to put yourself in the place of the person reading the content, asking yourself if, from that perspective, what you wrote makes sense.

No Writer Is an Island

Other sections touch on this, but you can’t do it alone. We, as writers, rely on mentoring, peer reviews, and feedback. Our community makes us stronger. We improve by learning from others and by teaching others too.

Find your community, inside or outside your organization. Take on challenges that force you out of your comfort zone. Get used to receiving objective feedback without taking it personally. Identify your most common mistakes and work on improving.

Once a Tech Writer, Always Tech Writer

Documentation becomes a natural consequence of any project after being a tech writer for a while. You understand the value and importance of creating at least a good README file.

I am now in a new role, my final form as a data scientist. But I approach my activities thinking if I leave enough resources for someone to continue my efforts.

I question documentation pieces and support teams with improving texts, presentations, and formal descriptions. I do this not only because they identify me as an “expert,” a documentation SME, but because it gives me a purpose and makes me happy to help where I can.

AI Can’t Replace You

I must inevitably include this current concern here. Tech writers everywhere are wondering if AI will take their jobs. I can only share my opinion here. I don’t think so.

As tech writers, curiously, writing is only a smaller percentage of what we do. It is a step in a complex process. Looking at a documentation plan and everything involved, you’ll see that AI can only support some activities, such as improving grammar or helping with writer’s block.

However, AI won’t schedule interviews with developers depending on their availability, ask the appropriate questions, record the information, consider its audience, talk to stakeholders, ask for peer reviews, and manage customer expectations.

Secret Survival Skills

Finally, I want to share a piece of advice. Being a tech writer is much more than technique and knowledge. I have seen excellent writers fail due to a lack of soft skills. It is not what we want to hear, but it is true.

Soft skills are many, but let me share two main challenges that writers face and how I overcame them.

Technical writing advocacy: Only some know what a tech writer does, our backgrounds, or our skills. Part of our day-to-day is to share this with team members and other parties. I have seen peers get discouraged because specific roles don’t value them or see how they can contribute. Do not get discouraged! Overshare, overcommunicate, and help them know how you create your strategy and why it is important. Use examples and hypothetical scenarios to share how documentation saves the day. Share your activity program and ensure it is in the overall project structure and execution.
Stakeholder relationship management: Customers and other key parties have expectations based on assumptions about your role. It is also part of your job to adjust those expectations respectfully. You’ll run into people thinking you must be in charge of taking meeting notes or even taking on project management responsibilities. Don’t just say, “I don’t do that,” patiently explain your scope and give them something more attractive. For example, explain you do not take notes at every meeting. Still, as part of your activity plan, you have specific sessions that you need to conduct and record to create a helpful document gathering critical information and details about a process currently having issues due to a lack of documentation. Try it, and see their eyes light up.

Resources

The following are some helpful resources you can consult about this unique craft: