Are you worried AI will make your role as a tech writer obsolete? Discover why a nuanced approach to AI is key to understanding AI’s limitations, and more importantly, why the human element is irreplaceable.

The buzz around AI is everywhere, and for a lot of us, it’s exhausting. We’re constantly bombarded with hot takes, from evangelists promising a new dawn, to doomsayers predicting the end of jobs. As Tom Johnson put it in his recap of Write the Docs: Portland 2025:

“...there’s a paradox about AI fatigue. Sure, people might be tired of seeing AI themes surfacing everywhere, but people are also hungry for AI knowledge.”

This paradox is one I know firsthand as a technical writer, and the reality is far more nuanced. 

Technical writing is all about bridging the gap between complex technology and human users. For the past several years, I’ve been working with AI firsthand, helping implement and maintain tools that augment our documentation and customer support. While AI has immense value, that value comes with a shared responsibility–and a healthy dose of anxiety.

Indeed, as Fabrizio Ferri-Benedetti noted in his 2025 technical writing predictions, many professions in the “periphery” of tech, from writers to artists and support agents, feel their roles are under attack. The paradox is that the very skills being questioned—the empathy and judgment required to connect with people—are precisely the skills AI lacks.

So, rather than fearing for our jobs, let’s acknowledge AI’s place in our work as technical writers. Let’s recognize that AI is not a person, it's a tool that requires a human to wield it with care. 

To continue producing clear, accurate, and useful documentation in this AI-revolutionized world, we need to understand AI’s limitations in these five critical areas:

1. Documentation accuracy

AI models, particularly Large Language Models (LLMs), are trained on datasets and learn to predict the most statistically probable sequence of words. They don’t understand facts or verify the truth. When faced with gaps in their training data or ambiguous prompts, these AI models generate plausible-sounding but entirely fabricated or incorrect information, also known as hallucinations. Inaccurate documentation can lead to consequences like: 

• Legal risks - Inaccurate docs in extreme cases could lead to security vulnerabilities and system downtime. False claims on product features could lead to legal disputes like Air Canada being held liable for its chatbot’s bad advice. This damages your company’s brand and reputation, and can result in fines, sanctions, or product recalls. 

• Broken trust - A user following AI-generated instructions that point to a non-existent button or incorrect command will experience frustration and wasted time. This erodes trust in the product and documentation, leading to declining user adoption, customer churn, and unnecessary increases in customer support caseloads and costs.

• Misinformation - AI doesn’t question its source material. When support teams and other internal teams rely on AI-generated documentation containing errors, it creates a cascade of inefficiencies. These teams waste valuable time manually verifying information that should’ve been accurate from the start, leading to longer response times, service level agreement (SLA) violations, and ultimately, wasted resources. 

Instead, human technical writers act as a safeguard for documentation accuracy. With our specialized skills, we apply the following features:

• Verification - We verify our documentation through testing and collaborating with authoritative sources like product managers, engineers, and subject matter experts. We ensure the documentation is factually correct in its step-by-step instructions and screenshots, and actually aligns with the live product. 

• Nuanced understanding - With our acquired deep domain knowledge, we understand context, user intent, and the nuances of technical processes. By understanding the product’s functionality and limitations, we proactively call out areas of confusion with clear writing and consistent terminology. We incorporate admonition notices and wayfinding elements to point users to other related content.

While AI can generate text, it remains a synthesizer of patterns, not a guarantor of truth. Human technical writers are crucial for verifying and validating, ensuring documentation–and the AI using it–is not just coherent, but correct. 

2. Documentation quality

AI's output quality is directly dependent on the quality, accuracy, and completeness of the data it's trained on. Poorly written, outdated, or incomplete source documentation will lead to equally poor AI-generated content aka “garbage in, garbage out”. Low quality documentation results in: 

• Bloated content - Unmanaged knowledge bases are often rife with duplicate content, conflicting instructions, or overly verbose explanations. Feeding this mess to AI results in an equally chaotic output, making documentation harder to navigate and diminishing content discoverability, which increases user frustration.

• Inefficient processes - Rather than saving time, relying on uncurated AI input often shifts the burden of quality control to the end of the content management workflow. Human teams then spend considerable time fact-checking, editing, and restructuring AI-generated text, negating efficiency gains and diverting humans from valuable work, like helping customers or tackling complex problems.

Instead, human technical writers act as guardians of documentation quality, ensuring it remains as useful as possible to its readers. Tech writers are crucial for producing the high quality content that can then be used to train AIs on, which includes these key attributes: 

• Curation - We curate information, reviewing, cleaning, validating, and updating existing documentation, preventing “garbage” from entering the system. 

• Governance and standards - We establish and maintain critical content standards, style guides, and terminology glossaries. This ensures consistency, clarity, and accuracy across all documentation to keep teams and AI performing effectively. 

• Continuous improvements - We extend beyond doc creation by continuously auditing existing content, identifying areas of improvement, and integrating feedback from users and subject matter experts, ensuring AI remains accurate, current, and optimized. 

AI doesn’t magically transform bad information into good; it only amplifies what it’s given:

“In the age of AI support, the quality of your documentation will determine the quality of your AI outputs.” - HelpScout in Building the Skills for the Sport of Support (2024)

The human technical writer is key in ensuring documentation at the source remains high quality so that all documentation, including AI-generated documentation, is as accurate and efficient as possible.

3. Critical thinking

AI’s models are skilled at generating text, but are often lacking in the critical thinking and nuanced understanding required for effective documentation. This includes the ability to interpret complex concepts, anticipate user needs, and bridge the gap between technical details and human comprehension. Without the human element, AI-generated text ends up being:

• Shallow - AI LLMs can detect patterns and synthesize information, but lacks true comprehension. AI can generate content that describes what to do, but not why it’s necessary, when it’s applicable, or the underlying implications of an action, unless also explicitly documented in its training data. Ultimately this leads to unhelpful interactions that can leave users frustrated and still searching for answers. 

• Reactive - AI generates content based on the existing data and explicit prompts. It can’t proactively identify potential areas of user confusion, foresee new user needs based on emerging trends or feedback, or understand the deeper underlying issue that users are trying to solve. This often leads to users reaching out multiple times, contributing to a poor experience. 

Instead, human technical writers bring in an indispensable layer of understanding that extends beyond any AI’s dataset. This includes the following traits: 

• Empathy - Through experience, user research, and inherent empathy, we anticipate user questions, potential errors, and the overall user journey. We prioritize the customer experience, proactively designing documentation that guides users efficiently, addressing pain points before they arise, and crafting content tailored to our audiences. 

• Information architecture - Beyond individual articles, we design the architecture and content strategies that optimize for discoverability, navigability, and overall usability. This involves making key decisions on structure, hierarchy, and content types, which require human foresight and understanding of human mental models.

• Collaborative synthesis - We interpret complex concepts, ask subject matter experts probing questions, and synthesize information from different sources to understand the “why” behind the “how”. This cultivates a foundation of accuracy and understanding of the product, allowing us to create truly comprehensive and actionable documentation.

Although AI has exceptional pattern recognition, it lacks the ability to understand the user’s journey and the strategic purpose of documentation. This cognitive gap makes the human technical writer essential in delivering the critical thinking and nuanced judgment that transforms raw technical information into truly effective, user-friendly documentation.

4. Customer experience

In an increasingly AI-driven world, documentation now serves two main users: the human user who needs clear, actionable guidance, but also the AI system that extracts, processes, and presents information. AI is becoming embedded into chatbots, search engines, and automated support everywhere we look. If not balanced well, the consequences can be severe on the customer experience: 

• Formulaic language - When content is optimized primarily for AI, it often includes simplistic language, keyword stuffing, and fragmented sentences. The result is output that’s robotic, disjointed, and difficult for actual human users to read. Overly verbose or apologetic AI interactions can increase friction in the customer experience, leading to abandoned chats and a higher influx of support requests for human agents instead.

• Repetitive content - AI often favours explicit and even redundant phrasing to ensure thorough understanding and indexing, directly conflicting with human preferences for concise, varied, and engaging language. Rewriting documentation solely for AI optimization can sacrifice human readability and comprehension.

• Ineffective problem solving - AI prioritizes recognizing and indexing keywords and explicit phrases to generate information chunks. These fragmented chunks are hard for users to understand without larger context, like knowing a feature’s purpose, prerequisites, or even its subsequent actions. Lack of troubleshooting options and common error awareness can lead to escalated support, frustrating AI interactions, and customer dissatisfaction. 

Instead, human technical writers bring the much-needed human touch into AI, keeping customer experience at the forefront while utilizing AI’s innovations pragmatically. Balancing the customer experience is achieved through these abilities: 

• User-Centric approach - We inherently prioritize our human audience, ensuring clarity, usability, and a positive user experience. We refine documentation based on direct user feedback, usability testing, and analytics reflecting human behaviour, ensuring the balancing act benefits user satisfaction as AI integration evolves.

• Strategic integration - We act as the crucial “human layer”, strategically integrating AI-friendly elements like clear headings, logical content structure, and consistent terminology, without compromising the human experience. We understand good writing practices for humans often align with AI best practices, but we always prioritize the human first. 

• Proactive problem solving - We collaborate closely with subject matter experts to understand common issues, troubleshooting steps, and opportunities to improve user experience through helpful documentation. With our deep understanding of user workflows and audiences, we implement escape hatches to help users out of bot loops and implement handoffs for issues needing human support.

AI’s impact on customer experience is highly variable, largely dependent on effective human oversight and the quality of trained data. Human technical writers are crucial for prioritizing documentation for human understanding and problem-solving, while strategically structuring it to allow AI to augment its discoverability and utility.

5. Ethical, legal, and sustainability implications

The rise of AI in, well, everything, also brings profound considerations beyond content generation. We now have to contend with significant ethical dilemmas, potential legal liabilities, and growing sustainability concerns. These concerns extend to: 

• Biases - AI is only as good as its training data. If trained on biased or outdated information–like gendered language, or racial and cultural stereotypes–it can perpetuate and even amplify those biases in its output, leading to discriminatory language, or content that alienates or misinforms users.

• Data privacy - Processing sensitive user data with AI introduces significant compliance risks (e.g., Payment Card Industry (PCI) compliance, General Data Protection Regulation (GDPR), and California Consumer Privacy Act (CCPA)). Without strict human-defined protocols and oversight, the risk of data exposure or misuse could lead to breaches of trust and compliance failures.

• Intellectual property (IP) infringement - Training AI often includes vast amounts of copyrighted material by artists and writers, sometimes without consent. Relying solely on AI-generated content can lead to costly legal challenges and customer disloyalty if it infringes on existing IP, or if content creators aren’t properly acknowledged or compensated. 

• Energy consumption - Training and operating large AI models consume enormous amounts of energy and water. Repeatedly generating content without careful consideration leads to an unsustainable increase in computational demands and a larger environmental footprint.

Instead, human technical writers provide the human oversight, judgment, and accountability that AI cannot provide. We utilize these key attributes: 

• Accountability - We bear the responsibility for our documentation’s quality and impact. We build in accountability and guardrails in AI, ensuring it delivers content from approved sources, and regularly reviewing AI-generated outputs for fairness, inclusivity, and accuracy.

• Strategic implementation - We strategically deploy AI only where it adds clear value, optimizing content to reduce excessive AI processing, minimizing environmental impact, and maximizing resource efficiency. We advocate for a sustainable and balanced approach without losing sight of business goals or the customer experience.

• Best practices - We understand the importance of legal and regulatory compliance, ensuring our documentation meets all industry standards like medical and financial regulations, and accessibility requirements like Web Content Accessibility Guidelines (WCAG). This mitigates risks related to misinformation, intellectual property, and compliance. 

AI has the potential to improve efficiency and productivity, but its true cost extends beyond development. Human technical writers are key consultants in the pursuit of AI innovation, lending their judgment, critical thinking, and commitment to responsible information dissemination.

AI as a tool, not a replacement

As we've explored, the notion that AI can fully replace technical writers in documentation, knowledge management, information architecture, and communication is a misconception. While AI offers impressive capabilities, it fundamentally falls short in: 

• Documentation accuracy - Where AI often hallucinates plausible but incorrect information that demands rigorous human fact-checking.

• Documentation quality - Where AI necessitates human curation and high quality content at the source.

• Critical thinking - Where AI fails to interpret complex concepts, anticipate true user needs, or ask the strategic “why” questions.

• Customer experience - Where AI can significantly degrade it with repetitive, unengaging content that fails to help humans solve problems.

• Ethical, legal, and sustainability implications - Where AI introduces bias amplification, intellectual property risks, and significant environmental costs from unmanaged AI processing.

Regardless of where you fall on the spectrum of AI being good or bad, technical writers can still leverage AI as another tool in their toolbox, one that offers:

• Analysis - Use AI for pattern recognition and as another perspective to help to identify potential product gaps and areas of improvement. You can then conduct deeper audits or validate these insights with your human judgement.

• Innovation - Don’t get left behind; learn and adapt to new technologies to stay relevant and keep growing. Actively experiment with different AI tools, provide feedback, share best practices, and champion your docs in the fast-changing economy. Ensure AI is used responsibly and effectively while keeping the customer experience at the forefront. 

• Intelligent automation - Design workflows where AI acts as a true assistant, seamlessly integrating into existing processes. Optimize prompts, manage AI outputs, and implement tools that enhance productivity without compromising quality or strategic control.

• Repetitive tasks - Offload mundane tasks like first drafts, basic summarization, grammar checks, and content localization to AI. Redirect your unique human skills towards high-value activities like strategic planning, content design, user research, and complex problem-solving, all while maintaining high quality and efficiency in your docs. 

Understanding AI’s limitations and its opportunities is crucial to being an effective technical writer. We translate information into understanding, and AI is now part of this equation. As Fabrizio Ferri-Benedetti wisely puts it: 

“...you’re still part of a profession that bridges the gap between humans and machines. And in an era where AI is reshaping every aspect of our work, that bridging role becomes more crucial than ever. The title on your business card might change, but the essence of what we do–making the complex clear–endures.” - Why I became a Documentation Engineer (2024).

The magic of writing–the empathy to understand a user’s frustration, the critical thinking to simplify the complex, and the creative nuance to craft a compelling narrative–remains a uniquely human endeavour. It’s this irreplaceable human touch that ensures documentation is not just correct, but truly effective, trustworthy, and engaging. That’s something that can never be outsourced to AI.

Are you all for the AI hype, a complete skeptic, or do you fall somewhere in the middle? Feel free to share how you’ve implemented AI into your technical writing practice, so we can all learn from each other.

✏️ Note: This was originally published for Hearing Health Foundation’s June 2022 issue.

Ever since I was young, I've been obsessed with getting complete information. Being born with bilateral profound hearing loss to two Deaf parents and having one hard of hearing sister meant a life of constant misunderstandings and questions. This lifelong pursuit for information would end up making me an expert in communication and lead me to my career in technical writing.

Exploring alternative forms of communication

This quest for information began as soon as I was born. My parents, who were also Deaf, had experienced so much adversity themselves. There was no hesitation in raising my sister and me in both the Deaf and hearing worlds if it meant better chances for success.

As a result, I was given hearing aids as a newborn. Next, I had speech therapy sessions to learn how to hear, speak, and read lips. I was also encouraged to learn my parents’ primary language, American Sign Language (ASL), which certainly came in handy around the kitchen table. My parents made sure that we knew about cochlear implants (CIs), a medical device that bypasses the damaged inner ear by simulating the auditory nerve directly to provide a greater range of hearing sensitivity. They left the decision of getting a CI up to us. Although I was happy with my hearing aids at the time, I changed my mind in my 20s and got one then. Suffice it to say, I had a lot of options to help me communicate with others.

Despite all the tools and resources I had at hand, I was losing information every time it was verbally communicated to me — like water through a sieve. It was especially frustrating during school, and I loathed having to rely on others to fill in the gaps. Copying the smartest kid’s class notes wasn’t enough; their notes were a summarized version of the complete information they had heard. Using a frequency modulation (FM) system to make the noisy environment clearer was useless; I was too reliant on lipreading (speechreading), so no increase in sound and clarity would fill in the information gaps.

It was no surprise that I preferred visual learning, and that evolved into a love of reading and writing. With all the information captured in words, I could read instead of fail to hear. Between closed captions on the TV and a never-ending supply of books, my reading speed and vocabulary rapidly surpassed that of my peers.

In the meantime, my appreciation for ASL as a visual language grew while I attempted to converse in sign with my parents, their Deaf friends, and a few Deaf friends of my own. This blended upbringing was incredibly valuable; it taught me that information could be conveyed in myriad ways, and each method had its own pros and cons.

I found beauty and diversity in the written word, from Shakespeare to an argumentative essay and everything in between, but also in the body language and spatial awareness of sign language. I wouldn’t realize it until many years later, but seeking alternative forms of communication through writing and ASL shaped my versatility as a technical writer.

Finding the right accommodations

As I got older, parts of my education continued to suffer from loss of information. There was only so much I could learn from books in certain subjects when so much of it was still being taught verbally. With the help of some incredible hearing resource teachers, a lot of petitioning on my part (including one persuasive speech to representatives at the Toronto District School Board), I was able to secure funding for a pilot of communication access realtime translation (CART) accommodations. In this pilot, a contractor with exemplary typing speed sat down next to me with their laptop, capturing all spoken speech into text that I could read in real time. It was my very own live closed captioning in the real world, and it blew my mind how much verbally communicated information I was missing out on.

The pilot was so successful that the CART accommodations extended into high school for some of my core classes. My grades shot through the roof and awards started trickling in. Thanks to government bursaries and grants covering the expenses, I continued to utilize CART accommodations in my post-secondary education at Ontario College of Art & Design University. Advances in screen-sharing apps also gave me back some independence because I could sit wherever I wanted in class, while still being able to see my notetakers’ transcribed text appear on my screen.

It also allowed me to practice a core skill that I was behind on: how to write my own notes. After every class, my notetaker would email me their notes — anywhere from 15 to 30 pages — for me to keep and use as I saw fit. I would take those original transcripts, quickly reread them, and rewrite my own separate notes containing only the salient information. Later, I would use my very own notes for studying and referencing. Better late than never — here I was, finally learning note-taking.

This, along with attending an arts university, also taught me how to explain creative works by communicating abstract ideas into clear and tangible terms, as well as developing my critical thinking and analysis skills. Without meaning to, I had learned how to extract important information from large swaths of documentation and how to communicate in an accessible manner — key skills in technical writing.

Improving documentation for others

It wasn’t until many years post-university that I realized I had a passion for information, and that I could turn it into a career. During my job as a customer support specialist for FreshBooks, I realized I wasn’t the only one struggling with access to information during onboarding.

Our support documentation was out of date, inaccurate, and disorganized. I had to depend on my colleagues through messaging them on Slack or shoulder-tapping them in person. I felt like I was reliving my childhood and having to rely on others for information, except it wasn’t just happening to me. This continued to bother me during my years in the role, where my product knowledge continued to grow and my communication and writing skills improved with every customer support email. My emails were often used as positive examples for new hires. My product knowledge grew to the point where people who had worked there longer than I had were asking me the questions instead.

When my team lead asked me the inevitable question of where I saw myself in a few years, I knew I didn’t want to become a people manager or move into a higher tier of support. It was through many months of brainstorming that I realized there was no dedicated owner for support documentation and my passion for writing made me a natural fit. I seized the opportunity, taking on technical writing as a side project while still working the job I was hired for.

I eventually amassed enough qualitative and quantitative data to pitch a brand new, full-time role for myself: managing documentation. With my fast reading and comprehension skills, I could synthesize information rapidly and communicate it in an accessible manner. I was already a technical writer without realizing it, and thankfully FreshBooks leadership decided to take a chance and make it official.

The journey never ends

Currently as a Senior Program Manager of Communications, I develop simple and fast access to accurate product information, and reduce support load by improving self-service resources for customers. In other words, I take complex information and rewrite it to make the information more accessible for others. After all, what better person to write thorough and accessible documentation than someone who’s had to rely on others’ notes their whole life? I knew how frustrating it was to not have all the information at hand, and to have to rely on others to capture that information in other ways for me.

In a way, my hearing loss forced me to acquire skills and experiences which turned out to be vital to my ambition for a career in technical writing. It gave me the ability to flex into various writing styles, the ability to synthesize dense information, and the ability to explain concepts clearly, along with the empathy required to understand the barriers in accessing information.

All of this would not have been possible without access to the tools, accommodations, and allies that helped advocate for me along the way. Some days, my being hard of hearing makes it difficult to do my job, and other days, it makes me better at my job because of what I’ve learned from it. But no matter what, I always look forward to writing and wrangling information every day.

People from all walks of life end up in roles or careers inspired by their shared experiences, like myself. International Day of Persons with Disabilities is celebrated on December 3 every year — what are you doing to help break down barriers to inclusivity, accessibility and sustainability every day?

I’m often asked how I got my job as a tech writer, because it was a brand new role that never existed before. My journey was a little unconventional, but the path I traversed through was invaluable; maybe it’ll inspire you to make your own too.

Trailblazers. Innovators. Leaders. What do they all have in common? They’re known for going off the beaten path, for taking the road less traveled. They’re also terms others have used to describe me and my unusual career journey. I started off as a frontline agent working in Customer Support, and then ended up becoming FreshBooks’ first technical writer… all because I saw an opportunity to take a little passion project and turn it into a full time role.

Figuring out what I wanted to do wasn’t straightforward, and I didn’t even know tech writing was a thing until I stumbled across it. I remember thinking my journey was a serpentine mess while I was in it, and now, upon reflection, I saw it as three fundamental steps: brainstorming, trial and error, and a business case that made my new role happen. Looking back, this journey was sparked by one simple question, one that we’re all inevitably asked at some point in our careers: “Where do you see yourself in a few years?”

1. Brainstorm the next step

I knew my strong communication skills and unwavering passion for helping others was a natural fit for the role of a frontline support agent. Though I didn’t see myself in this role long-term, I believed it was a good stepping stone. After enough time had passed and I was comfortably cranking out support cases on my own, then came the dreaded milestone: planning my career progression. A conversation I was avoiding because I didn’t even know what I wanted to do next.

Assess the current options:

Figuring my next step started with understanding what available career progression options there were for someone in my role. Usually for customer support agents like myself, it was either move into a higher tier of support (like technical support) or go into management and manage a team of several agents. Neither of those appealed to me, much to my team lead’s dismay (who thought I would be a natural candidate for management!), but they were supportive nonetheless. Even though I didn’t know what I wanted to do next, I knew that the current paths weren’t sparking joy for me. I had to keep looking elsewhere.

Look for ideas:

At my team lead’s recommendation, I devoured any and every resource I could find around career planning, growth and development, and then some more. I learned a little bit more about myself each time with every career book, blog post, personality test, brainstorming exercise and TED talk I studied. I had no clear goal for this, other than to just keep absorbing and trying new things until something resonated with me. Then, I stumbled across a question buried somewhere, and it was like as if the Force became one with me:

If you could do anything to make the company better, what would it be?

It immediately came to my mind:

Documentation.

When my team lead asked why, I had no trouble coming up with a myriad of reasons. I enjoyed writing my whole life, especially explaining new concepts to people in a clear and accessible way. Not to mention, no one was managing our Help Centre or our internal product knowledge, both of which were out of date, inaccurate and disorganized. Both folks in Support and new people being onboarded were constantly asking questions on Slack, or shoulder-tapping in person, which was costly.

Clearly I was onto something here; an unexplored opportunity that could allow me to utilize my passion. My mind was already spinning up a huge to-do list that would address this problem in different ways. Now I didn’t have to dread career conversations anymore; I had a project that made work exciting again.

* * * 

Career planning is useful, even if you don’t figure it out right away. Knowing the current options for my role was helpful in allowing me and my team lead to start thinking about other ways I could progress. Instead of being forced to pick a path I would’ve been unhappy with, the career conversations allowed me to discover a side project I could work on over time.

Leaders, support your employees by giving them time and space to consider their career paths. Individuals, utilize every opportunity to learn and reflect while planning your future career trajectory.

2. Plot the journey

Now that I identified an area I was excited about, I finally had a direction to aim for. I wanted to move forward with this newfound project, but I didn’t know where to start next. Because I was the first one to really say no to the current career paths offered, I had to figure out how to pursue this new passion while maintaining my current role. I was on my own, charting a course without a map to follow.

Meet current expectations first:

First, I had to make sure I met my expectations as a frontline agent, as in, the job I was hired for. That meant completing my cases while meeting or exceeding the expected quality and quantity for the role. This proved not only that I was professional and responsible, but that I cared about doing my current job well even when I wanted to take on a new side project.

Negotiate new expectations:

Once I met my current requirements, I worked out an agreement with my team lead where any spare time I had could be used to work on this passion project of mine. This was really helpful on slow days and motivated me to take care of my frontline requirements as early in the day as possible so I could do the “fun stuff” in the afternoon.

Increase time spent on the project:

After proving that I was meeting my expectations, I would make sure to identify all the tiny victories from my project and share them with my team lead. This was useful during performance reviews, where we were able to reduce my case expectations so I could have more time to work on this project. The increase in spare time on the project meant I could tackle more work which would translate into more accomplishments and improvements.

Incorporate the project into expectations:

At this point, I found myself at a stalemate; I had already gotten my case expectations decreased, and I was maximizing every minute of any spare time I had… but it wasn’t enough. Some days were harder than others, and often translated into not having spare time for the project until near the end of my shift. After many discussions with management, we worked out a new arrangement that was less dependent on hitting my case count every day.

The arrangement: as long as I tracked my time spent on this project, my team lead would convert that time into cases to add to my overall quota. Whenever it was a slow day for cases, I’d switch to working on my project, and send the tracked time to my team lead, so it would always contribute to my overall total cases worked. To help formalize this even further, my team lead and I worked to add my project milestones into my performance evaluations. Making the project officially part of my goals and progress allowed me to measure and account for the work I was doing on a regular basis.

Move the project into full time:

Lastly, it was clear I enjoyed working on this project instead of working on frontline cases, and that it was only the tip of the iceberg. When I spent more time on it, this correlated to bigger improvements and spawned many additional subsequent projects. My performance reviews were always praising the work I spent on the project, and there was no shortage in developing additional project-related goals despite working on them over time. The course I was charting was leading to a final realization; this was more than enough work for a full time role, and I wanted to make it happen.

* * * 

Build up your credibility with on-the-job development and increase from there. With a project that had me excited about work again, I took the initiative and carved out time to work on this project while maintaining my role expectations. This incremental approach allowed me to negotiate for more time on this project by using my small accomplishments and past performance reviews as a bartering chip.

Leaders, support your employees by giving them room to experiment and try new things to keep work exciting, and ensure it’s captured in their performance reviews. Individuals, use a project to stave off low job satisfaction, build up skills and gain further experience. An employee that’s always self-learning is better than a stagnant one.

3. Document everything

At this point, I had been working on frontline for over a year and half, with several months devoted to this project of mine already. I had built up enough credibility as an exemplary employee to try doing the unthinkable: ask to work on this project full time.

Utilizing the resources and people around me, I determined that my best chance of creating this new role out of thin air was to convince support leadership, since they were the ones responsible for budget and headcount. To maximize my odds of succeeding, I also had to deliver this request in a way that they couldn’t say no: by speaking their language, and by demonstrating the value it would bring to both the department and the company as a whole. It was time to craft a compelling business case, and pitch it to them.

Prove the value of the work with key data:

In order to justify the need for this project to become a full time role, I had to incorporate both quantitative and qualitative data. Firstly, I tracked all the time I had spent on this project, down to the minute, which I had been doing from the beginning as part of my arrangement to supplement my current case quota. Having the historical log of time tracked was useful in helping me forecast future workload on this project.

Secondly, I tracked the improvements and accomplishments that came from the time spent on this project, and tied it back to metrics that I knew the people I’d have to convince would care most about. For example, showing the average time our agents spent on tickets before and after I made specific improvements, or showing increased pageviews on an article I rewrote. Having this list of accomplishments and valuable metrics helped me in conveying the positive impact of my project in a way that was easy for others to recognize.

Assemble a presentation:

Knowing I would have to deliver my pitch as a presentation along with the key data I collected, my team lead and I reached out to support leadership for a few things:

• First, to identify the stakeholders that would be making the decision so I knew who to invite to my presentation meeting;

• Secondly, to ask if there were any additional criteria or considerations that needed to be included in the proposal;

• And lastly, to plant the seed of change management, so that these folks were aware of my upcoming proposal, especially if there were deadlines around budget planning that would impact their decision.

This was also partially a strategic move that allowed me to put myself on their radar and to give myself the best chance possible of making the most persuasive presentation. The research that I collected, along with my data, started to inform the outline of my business case:

• Introduction  - Sharing details about my tenure, experiences and relevant skills to build my credibility and qualifications

• Problem  -  Identifying the problem that needs to be solved, and issues that impact the department/team

• Benefits/Needs/Opportunities  - How the problem can be solved with a full time role, including a mission statement and details of future work

• Goals/Metrics  - How to measure the impact of my work through success metrics, key performance indicators and more

• Plan  - Future-proofing the role by specifying the duties/responsibilities and team structure

• Conclusion  -  Restating the problem, and how the full time role would solve it, and offering Q&A to wrap up any loose ends

With this outline in place, I was able to put together a presentation that articulated and encompassed all my work and the positive impact it had on our business and department. Now all I had to do next was present the pitch and hope for the best.

* * * 

Make it hard for others to say no with documentation. By tracking my time and achievements on this project, I had built up enough credibility to make a pitch to the support leadership team. This, along with identifying the key details I needed to make the strongest case possible ensured that I would be speaking their language fluently.

Leaders, set your employees up for success by connecting them with the right stakeholders and finding the right metrics to capture from the very start. Give them the tools they need to help them make the best business case for their career progression. Individuals, if you’re serious about taking your project to full time, take initiative and show your dedication by speaking the language of leaders with a well thought-out proposal that showcases your impact clearly.

The road so far…

One nerve-wracking presentation and many days of waiting later, I got the exciting news: my very own brand-new full time role entirely dedicated to documentation. Since the inception of my role, my department’s implemented a new program to build in personal development time for our more tenured frontline agents, and there’s now many more new career paths besides management and technical support. I’ve also become an unofficial mentor to folks looking to create their own path by sharing my story and the lessons learned, inspiring others to follow their passions too.

If there’s anything to take away from my story, it’s these three things:

• Build in brainstorming time  -  Whether it’s personal development, innovation, or career planning, it’s so valuable to have this dedicated time to research, to absorb, and to spark conversations with your manager or direct report. This can help uncover any hidden passions or interests that could help the business at the same time.

• Plot the journey  -  Work together with your manager or direct report to ensure that there’s always time carved out to work on this passion project, while managing expectations. From there, increase the time spent as trust is earned and responsibilities are maintained.

• Document everything  - Track all time and all efforts, and use this to make the case for a full time role if it’s needed. Regardless, you’ll still end up with a great highlight of your achievements and a greater understanding of where you like to spend most of your time for future projects.

In all the mentoring conversations I’ve facilitated, these were the three key points I stressed, along with accepting discomfort and uncertainty. I had no idea what my future would look like, and that was okay as long as I kept moving forward.

At first, it was strange having to build out my brand new role and figure things out as I went along. I was constantly adapting; plotting out my duties and responsibilities as I discovered them, coming up with goals and metrics to report back to leadership on, and working in a role where meeting a quota at the end of my shift was no longer required. Over time, I switched from being reactive to being more proactive, and shifted my focus from accomplishing goals in the next year to developing strategy plans and setting a vision to guide my role for the years to come.

I wouldn’t change what I went through for the world; it’s taught me that I’m a trailblazer, unusual and resilient, and that many years later, I keep finding new projects and coming up with ideas to keep me motivated. Though it’s cliche, it’s still true for me — I’m always excited to go into work every day and continue my passion of writing clear documentation.

If you’ve had to create your own job or career, I’d love to hear what you’ve learned along the way for others in our shoes. It’s time we made unconventional career journeys less mysterious and more commonplace!

✏️ Note: This is Part II of How to choose the right tool for your docs (Part I), which you can read first if you haven’t already.

Are you struggling with the limitation of your documentation tools? Or have you been presented with an opportunity to pick a tool to start building your documentation on? Set yourself and your team up for success with lots of preparation - so that you can choose the right tool, migrate your content seamlessly and encourage adoption amongst your team easily.

👋 Heads Up: This was also delivered as a talk for Write the Docs: Portland 2020. Review slides here or watch the talk here!

To recap from How to choose the right tool for your docs (Part I), half of my documentation vision is ensuring we have simple and fast access to accurate product information. We knew that our current tool wasn’t supporting this vision, and we identified a new tool that could.

As someone responsible for maintaining our Customer Support team’s docs at FreshBooks, I was faced with something that I had never dealt with before: migrating our docs to a brand new tool. Where to begin? How have others done it? It was exciting but also terrifying. It was also a rare opportunity to start over, but with so many people relying on our docs, expectations were high…

As Yoda says, “always pass on what you have learned”, so learn from our migration journey so that yours is as successful as possible — a seven-step process to help you prepare, anticipate and overcome anything that arises during your migration.

1. Create a project plan

Like any journey, it begins with the first step. A project plan helps you track your work, manage your time and keep your stakeholders updated.

Whether you’ve got the green light, or maybe you’ve finally put contract negotiations behind you with an active subscription for the new tool, resist the urge to dive in and start writing all the things. Take a step back and put together a project plan first. Doing so will give you an idea of how much work is required every step of the way, and hold you accountable from start to finish.

If your company has project managers like mine, you can always copy from one of their templates and modify it, or make your own from scratch. A good project plan for a content migration should include the following:

Project Plan Template:

• Project Description  -  This should include why you’re implementing this tool and the goal of your new tool, in case a new person (or stakeholder) looks at it

• Business Case  -  Include details on why this project is happening, or link to a presentation deck you’ve put together (you can outline the problems you’ve identified from your data in Part I).

• Stakeholders  -  Specify who is responsible for which part of the project; it also makes it easy for folks to reach out to the right person if they have questions.

• Priorities  - Outline where you’re flexible and least flexible with scope, schedule and budget/resources/people; this is how you prioritize tasks as they come up.

• Project Schedule  -  Provide or link to a calendar, Gantt chart, or something that visually depict the timeline of this migration (and it’s okay if your timelines are rough estimates for now).

• Tasks  - List all of your to-dos (every single one of them), and feel free to bucket them in sections or categories to make them look less overwhelming — checkboxes are optional but very satisfying to check off!

• Project Communications  - Outline what kind of communications you’ll be sending out (whether it’s a meeting, an email, or even a slack message), to whom, and the frequency. This sets stakeholders’ expectations on updates from you.

• Risk Management Matrix  -  Specify any potential internal and external risks that could delay or derail your migration, their impact, the mitigation strategy or action you can take for each risk, and their status (mitigated, caution, critical). This is how you anticipate obstacles before they occur and how to handle them should they arise.

Use a project plan as your second brain. A good project plan has everything documented, and is always up to date as you progress through your migration. It should be the first tab you open at the beginning of your work day, and the last tab you close at the end. After all, Princess Leia didn’t just steal the Death Star plans, did she? She planned it first.

2. Audit your docs

Next, you’ll want to evaluate your docs to ensure all of your migrated content is up to date and useful.

You have an opportunity to start fresh, especially if you’ve inherited a hot mess or if you have no idea what kind of content lurks in the darkest corners of your documentation. Auditing your docs allows you to ensure your new tool is set up for success with immediately useful docs.

Auditing Tips:

• Centralize Your Knowledge  - If it’s the first time you’re organizing docs, make sure you have everything in one place to audit first. Or if you’ve already centralized your knowledge, double-check you have everything.

• Catalogue Content  - Catalogue all your gathered docs into an index or a table of contents so you have a birds’ eye view of everything.

• Assess  -  Go through your catalogue and determine what to keep, what to change and what to omit. Don’t forget to add missing content that may have never been documented too. There are lots of labelling/rubric systems out there that you can use if you need some help:

  • ROT  -  Redundant, Outdated, Trivial

  • OUCH  -  Outdated, Unneeded, Current, Have to Write

  • YMNW  - Yes, Maybe, No, Write

A blank slate equals an opportunity for clean docs. Use this time to audit everything you have before you move it to save yourself time and headaches. Your users will thank you for giving them useful docs. Don’t lose momentum by getting stuck in the nitty gritty of editing each and every piece of content you come across — use the catalogue to keep it high level for now. After all, you want to keep powering ahead like the Millennium Falcon on the Kessel Run.

3. Build the foundation

Next, you’ll need to consider how you want your information to be organized in your new tool while you’re in the early stages of your migration. Everything is generally easy to manipulate before the content’s added in. With a catalogue setup, you can now start building your foundation by establishing the information architecture and tagging structure.

Utilizing Information Architecture:

• Information Architecture (IA)  - IA is all about the organization, structure and labelling of content in an effective and sustainable way; or in other words, the hierarchy of your content. Look at your catalogue — does it make sense and is it easy to find content based on the categories and sections you’ve organized it into? Otherwise, reorganize it as you see fit.

• Card Sorting Exercise  - This is a great UX testing tool that you can try with a few of your users (ideally with various levels of experience). Write out each individual item from your catalogue onto sticky notes, then ask your users to organize those sticky notes into a hierarchy that makes sense to them. You can then try to build an average IA based on the card sorting results; the more the IA makes sense to your users, the easier it will be for them to find the docs in your new tool. (Review how two of my users organized our IA).

• Search and Tags  -  Use your IA to build your tags or labels to provide shortcuts for your users to search with in the new tool. You can also set up best practices for how to tag content, what tags to use and when to create new tags in the future.

A strong foundation leaves room for docs to grow. Planning your information architecture from the beginning means it’s easy to add or modify the structure in the future, and you can use the IA to help migrate content piece by piece. After all, fundamental understanding of the Force is essential to becoming a Jedi.

4. Prioritize in blocks

With your IA set up, you can start thinking about your time management for this migration. When it comes to figuring out the timeline, it’s best to go into it with no expectations. Divide up your work into smaller blocks, then you can estimate your time based on a block instead of generating random guesstimates. The smaller your blocks are, the easier it will be to re-prioritize when surprises come up.

Time Management Tips:

• Implement your IA  - Use your new IA to create those folders, categories, sections, boards, pages, whatever this new tool uses to organize your content. You’ll gain confidence while working on a blank slate as you get more familiar with the new tool, and you’ll get a better idea of how much time it takes to create new content. This will help you make more accurate time estimations.

• Break up your Work  - Divide up your IA into small chunks, and prioritize it in an order that makes sense to you. If you’re organizing content for the first time, you might need to prioritize your most important content first. Otherwise, you can start with something simple and easy first, and save the complex content for last, so you have room to make mistakes and play around with formatting.

• Understand your Productivity  -  Ensure you and your manager are on the same page about your time to this project. If you have to balance migration work with other duties, schedule your migration work where you’ll be less likely to be interrupted, and leave room in your day for surprises, meetings, and catch-up time. Protect your migration time as much as you can.

Prioritization makes for a smooth journey. Take control of your migration project by breaking it up into blocks, and by intentionally ordering those blocks. The smaller your blocks are, the easier it is to manage your time and avoid costly interruptions. Remember, it’s a journey. The Death Star wasn’t built in a day!

5. Make change easy

Change can be scary for some people, especially if you spring it on them suddenly out of nowhere. Even though you’re migrating content, you also need to think about how to get your users onboard too. Keep your users in mind from the beginning, and introduce changes to them gradually. Your users will determine the success of the tool, so early communication and awareness is key to a successful launch.

Launch and Training Plan Tips:

• Recruit Beta Testers  -  Beta testing is a useful way to let a few users test something before you release it to everyone else. Gather a few users from different levels of experience and seniority and let them use the new tool with some content in it. Get as much feedback as you can in the early stages of your migration so you can course-correct as soon as possible.

• Keep your users informed  -  Let them know a new tool is coming and get them excited about it by highlighting some key features to drum up excitement. Present a quick slide deck at the next team meeting, and send out teaser emails. Do this often over the project schedule so it feels more gradual than sudden.

• Build a training plan  -  A new tool requires training — how are you going to train all of them? Who will do the training? What do you want your users to learn, what functionality needs to be covered? Answering these questions will give you a framework to build a lesson plan from.

A tool’s success depends on its users. Your tool will only be successful if your users buy in too — and doing it early on will make it easier for them to adapt and adopt. You don’t want your users to get angry like a Wookie who has lost a game of Space Chess, do you?

6. Embrace flexibility

When migrating content, it can be a rollercoaster of excitement and drudgery. The key is that you’re migrating content intentionally and at your own pace. Use your productivity to keep your motivation high. Follow your project plan, stay on track with your blocks and be ready for anything while moving content.

Stay Flexible:

• Utilize your checklists  -  Check things off as you complete your tasks, and use your catalogue to strike out or highlight items as you move them over to the new tool to keep track. Seeing visible progress will keep your motivation high.

• Be flexible  -  Be ready for anything, and quickly pivot as needed. Don’t be afraid to expand your project plan while you’re migrating content; keeping it all written down means you can focus on your block without getting overwhelmed or distracted.

• Take breaks often  -  Give yourself breaks every now and then. When you clear out a block, take a moment to celebrate and marvel at your progress. Feel free to share your progress with your team and stakeholders as needed.

The mindset determines the experience. Migration will seem less intimidating when you have the mindset of being flexible and prepared. All the previous steps you’ve done up until now will give you the tools to handle anything during your astronomical migration. As Qui-Gon Jinn would say, “your focus determines your reality”.

7. End with reflection

At this point, you’ve completed the migration, you’ve delivered hours of training, and your users are finally using the tool — you may have even celebrated with a launch party. But the journey isn’t over yet. Reflection and post-migration tasks will ensure you end the project with the closure it deserves, for you and your users too.

Reflect With:

• Conduct a Retro  -  in Agile methodology, a retrospective (retro for short) is held at the end of a sprint to discuss what worked and what didn’t. You can reflect on skills you’ve used like time management and collaboration, and analyze processes so you can apply those lessons in the future. You can use any retro activity, but my preferred one is the sailboat with some modifications:

  • Sailboat  -  Represents things, people and processes that helped accelerate the migration project

  • Anchor  -  Represents things, people and processes that slowed down the migration

  • Sun  -  Represents what made us happy during the migration

  • Iceberg  -  Represents what could negatively impact the new tool or put it at risk

• Feedback Cycle  -  Future-proof your new tool so that it’s always useful and relevant to your users as your product and team grows. How are your users going to pass feedback for missing or outdated content to you? How can they get support when they’re having trouble using this new tool? A feedback cycle will ensure your docs can scale over time.

• Follow up with Stakeholders  -  Your stakeholders will appreciate hearing back from you on how the migration went, especially if a lot of money was spent! Share a high level summary of your retro, how the feedback cycle will work, and any data you’ll be tracking to determine the success of your tool.

Rituals help end the project on a good note. Give your migration the ending it deserves, because you’ve spent a lot of time planning this migration and executing on it. Some reflection will bring you a deeper understanding of your skills. Although your migration project is just the latest chapter of your documentation story, this new tool is the beginning of a new saga.

…and now, your saga begins

Migration is about moving your docs efficiently with minimal disruption to your users. With a successful migration, your users are better educated and more empowered to find information in your tool. Most importantly, people are finally reading your beautiful, well-written documentation!

Are you considering a new tool or is your tool working really well for you? Let's learn from each other and make documentation better.

Are you struggling with the limitation of your documentation tools? Or have you been presented with an opportunity to pick a tool to start building your documentation on? Set yourself and your team up for success with lots of preparation—so that you can choose the right tool.

One part of my vision for our documentation is to develop simple and fast access to accurate product information. At FreshBooks, all of our Support team's coveted product knowledge was housed in Confluence, which also included other content written by the rest of the company. However, finding Support-specific information in the vastly, hugely, mindbogglingly big wiki sea was neither simple, nor fast, for our Support team to access.

In fact, our Support agents dreaded using Confluence, and preferred to go ask their own colleagues or experts instead. We were also growing fast in several areas: in support volume; in new hires; and in releasing new improvements and updates more frequently.

When you connect all these dots together, it paints an alarming reality - our knowledge was too high-effort to use, and it was hurting our agents' productivity. This in turn was hurting our customers, who were waiting on that knowledge. Our tool was not working well, and it was not supporting our documentation vision. It was time to look for something better.

Maybe you're nodding in sympathy with our story, and you want to know how it ends. Or you're at the same fateful crossroads of determining where to set up shop for all your docs and you don't know where to begin. Either way, use these five steps to get started to identify a new tool, one that will actually allow your users to find and read all of your documentation.

1. Identify your users’ problems first

In order to look into alternatives to replace your current tool, start by proving there’s a problem first. If you have lots of anecdotal evidence like I did, it’s helpful to corroborate it with data from your users so that it’s easier to persuade your stakeholders (like your leadership team and/or executives) to say yes.

When it comes to collecting data, reframe it into questions that you want to see answered first. Once you have questions put together, you can then collect data to answer those questions, like a survey. I began with three key questions that I knew my stakeholders would ask:

Example of our Questions:

• What is the state of our docs currently?

• What are the specific problems affecting our users (Support)?

• What are the metrics I can measure to determine the new tool’s success?

And in case my stakeholders wanted specific data, I started thinking about how I could break up these questions to be more specific and targeted. From there, I came up with a survey of 4 questions that I sent out to our Customer Support team, one of which I left open-ended to collect testimonials:

1. How much do you trust the information on the wiki? (on a scale of 1–10)

2. How easy is it to find the information you need on the wiki? (on a scale of 1–10)

3. How often do you use the wiki on your cases? (on a scale of 1–10)

4. Any feedback on the wiki? Any things in particular that you find frustrating, or things you’d like to see improved?

Understand the problem first before finding a solution. Identifying what kind of problems you have will help you formulate a convincing argument to your stakeholders. The stronger your data is, the more compelling your request will be, and the harder it will be for your stakeholders to say no.

2. Synthesize the data with extra data

Obi-Wan Kenobi said it best, “your eyes can deceive you, don’t trust them.” Even though you may have identified problems based on your own survey or research, it helps to get extra data to paint a bigger and more accurate picture of the state of your docs today. Your stakeholders probably already utilize metrics related to the department’s efficiency, productivity and headcount, so why not use them too?

Utilize their data and merge any key elements that help supplement the data you’ve uncovered about the problems that you’re trying to prove. With your combined data, you should begin to see patterns or trends that can help you summarize your problems with key insights like these ones I uncovered:

Example of our Key Insights:

When I reached out to my stakeholders, I asked for access to their data — this included metrics like average cases per support agent, support headcount, how many wiki pages were owned by Support vs. other departments, and more. This, combined with the survey data, gave me the rest of the information to identify three key insights affecting our Support team:

Too Much Time on Cases (Poor Search)

• Our agents were spending 12% of their time trying to find information on our wiki every week

• A journey mapping session on agents’ workflows while working on support tickets revealed using the wiki was 1 of the 3 top pain points

• Our knowledge was getting drowned out, with 3% of all content in our wiki being support-related pages we needed our agents to reference daily

Too Much Dependency on Experts (Low Trust)

• Support agents were dependent on our Subject Matter Experts (SMEs), pinging them on Slack or in person for answers

• Qualitative data revealed that agents were making assumptions that if the top of the wiki page says “Last Updated by [Name] on [Date]”, it must be out of date… even if the information was still correct

3. Limited Functionality

• Support was already juggling multiple applications with our setup

• Onboarding was slow and laborious with learning various systems simultaneously

• A lack of analytics on Confluence meant we couldn’t track and improve searches, or see how certain content was performing/being utilized by our agents

Utilize your data effectively to maximize buy-in. Combine your data with other data that your stakeholders care about — this will help them see how this problem you’re raising may impact their metrics, or how a new tool could bring in improvements to certain metrics. Summarizing your data with key insights will help your stakeholders listen to you more carefully as you propose a new tool.

3. Establish requirements

Your next step is to then figure out what requirements you need for this new tool to be successful. It’s important to do this before you start looking at vendors for new tools. The last thing you want to do is to make a quick decision that could backfire — you don’t want the new tool to be a waste of your company’s funds and resources, or end up being ignored by your own Support agents.

• Focus on your audience  -  No single tool is right for all situations, and this is true even inside your company — what works for one department may not work for the other departments. It’s important to determine who will need access to your documentation first so you can understand which tool will work for your users.

• Separate must-haves and nice-to-haves  -  Understand what features are critical to your docs’ success and what are less critical but nice to have features. Separating them out will help you compare tools more fairly.

• Avoid unnecessary features  - Don’t get sidetracked about shiny features that don’t actually address an actual need you have, and don’t put them down as a must-have.

For inspiration, check out business requirements by other departments at your company, or Google others’ lists of requirements like this one.

Example of our Requirements:

For us at FreshBooks, we wanted a tool that would be used by both Support and Sales to look at product information (basically, how does our product work). This would live separately from our company’s Confluence wiki, where a myriad of information that was not relevant to support could live. These were our hard requirements:

• User friendly  -  So that both our agents and any new hires so could pick it up quickly

• Integrates with Zendesk and Slack  - It’s where Support spends most of their time daily

• Powerful search experience  - We want to tag content and categorize, or reduce searching with machine learning/AI

• Isolated from Confluence Wiki  -  We want to ensure all the content is 100% support-related

• Bridges with external content (our Help Centre, which is hosted on Zendesk Guide)  -  To help decrease repetitive and redundant information

• Effective and robust content management  -  To easily scale as we grow in size and as we ship new features

• Analytics  - So we can track usage and drive improvements, essentially creating a feedback loop to constantly improve the experience

Set expectations before you shop around. It’s easy to get caught up in the shiny bells and whistles that some tools offer compared to others, which is why setting your requirements beforehand is crucial. Knowing what features you need will help you evaluate each tool fairly, and you’ll be much more successful at finding the right tool to match your users’ needs.

4. Research all the tools!

When testing every tool out there, it’s helpful to have a comparison table ready that you can fill out with pros and cons for each tool, and each business requirement as its own row. This makes it easy to illustrate which tool scores best in each requirement, and if your stakeholders want to see the details of this comparative work, this table serves as excellent proof.

Test each tool against all your outlined requirements that you’ve put together in the previous step, and see how each performs compared to others. You can also give some requirements more points, so they’re scored more heavily in case you have to prioritize certain features over others.

You’ll also want to include these extra factors in your research:

• Support  - Test the tool’s Support channels too — you should be able to get ahold of them easily when you need to, especially if you have questions, feature suggestions or feedback.

• Reliability  -  Look at the vendor’s Uptime — most tools should have a status page of their own; look at their history of downtime and issues; you want to be sure they’re as reliable as possible so that your documentation never doesn’t go down as often when your agents need it.

• Pricing  -  Get all pricing quotes in writing — you’ll need to compare costs with real numbers, not rough ballparks for your stakeholders.

Example of Tool Research:

In our case, I used icons for scoring and used a tally so I could quickly determine visually which tool met which requirements.

The best decision is a well informed one. Doing your due diligence with research and comparisons across as many tools as you need will ensure that you are choosing the best tool to solve the problems you’ve identified. Having this information will also help you convince your stakeholders that the tool you’ve identified is worth the price if it meets the requirements you’ve established. Let the Force be strong with the tool you’ve chosen.

5. Next, persuade your stakeholders

Now that you’ve chosen the tool, you’ll need to convince your stakeholders to agree as well. If the price tag is hefty, you might even need to convince an executive too. You’ll likely have to put together a business case for this new tool in the form of a document or a presentation, which you might’ve never done before. At this point, you’ll want to do these things to ensure you maximize your stakeholders’ time:

• Drum up excitement  -  Don’t let your pitch be the first time your stakeholders hear about this new tool. Set the groundwork by mentioning it in team meetings, or keep your manager apprised of your progress so they can share it in high-level meetings, especially before budgeting season well in advance.

• Speak their language  - Ask your stakeholders what they need to see in the proposal or slide deck, and use this to determine the outline of your business case. They may ask for financial information as well, like how much money would be saved with this new tool. If you’re new to crunching big picture numbers, your manager or a stakeholder you have a closer rapport with can help you out with this.

Example of a Business Case:

My powerfully persuasive pitch deck looked something like this:

1. Documentation Vision  -  The goal we’re trying to accomplish

2. Problems Facing our Department  - A summary of the three key areas identified from the data

3. Needs and Requirements Identified  -  What matters to us when evaluating any tool

4. Tool Comparisons  -  A recap of the research completed and the comparisons between tools

5. The Winning Tool and Key Features  - Background information on the new tool and their best features that met our key requirements

6. Metrics for Success  -  What data we would collect to measure the success of this new tool

7. Cost Breakdown  -  How much the tool would cost and any extra added fees

8. Q&A  -  Room for stakeholders to ask questions, objections and more

Win over your stakeholders with a compelling case. Summarize all your work so far with a business proposal or presentation that highlights the problems you’ve identified and why this new tool would solve all of them. Backing up your case with quantitative and qualitative data will make it easier for your stakeholders to say yes to effective documentation.

… and now the fun begins.

If you’re given the green light, now you get to begin the exciting second half of your journey — the big, great migration, and convincing the rest of your team to use this new tool! Read How to successfully migrate docs to a new tool (Part II) to learn more about how I got the new tool implemented for our Support department.

Are you considering a new tool or is your tool working really well for you? Let's be each others' Yodas and make documentation better for all.

What are tech writers, and why is having one managing your Customer Support’s Knowledge Base so valuable? I share my experiences as a FreshBooks Support Communications Specialist aka tech writer.

Tech writers, also known as documentarians, or by a myriad of other names (like Support Communications Specialist), are folks who handle documentation and communication in the software industry, regardless of their job title (source). In my case, a writer like myself is responsible for creating, editing and managing content in knowledge bases for teams (e.g., Customer Support) and/or for customers (e.g., a Help Centre).

If you work in a company with a Support department and you have customers who self-serve themselves, chances are you have a knowledge base of some kind, whether it’s internal, external or both. So ask yourself this — is all the content 100% up to date and relevant?

While you mull over this question, did you know that 75% of customers prefer to use self-service to address their customer service issues according to Zendesk? That’s a majority of your customers, and a lot of attention on your Help Center.

What if you don’t have a Knowledge Base and/or Help Center, or yours isn’t quite helpful enough? Then your customers will turn to your Support team. Is your Support team collectively ready to handle any question that comes up?

A study by Forrester found that 42% of customer service agents are not able to provide relevant information to customers due to a lack of easy to access information.

So back to that original question — if your content isn’t 100% up to date and relevant, you’re failing your customers and your support agents.

It’s worth it to invest in your knowledge bases to serve most of your customers and to help your support agents. Part of my role at FreshBooks is to ensure that our Help Centre is as effective as possible so that the majority of our customers can use it, and so that our support agents can rely on it when troubleshooting.

Need more reasons beyond the statistics presented? Read below for 7 reasons why your Support team needs a tech writer dedicated to documenting all the knowledge for your Support team and customers:

1. Ownership

Treat your company’s Knowledge Base like it’s a product. If it’s frequently changing (like most products in the agile world), it needs someone to own and maintain the information that Support and customers have access to. Having a champion (in this case, a tech writer), allows your Knowledge Base to: stay up to date with new features and improvements in a timely fashion; get the love and attention it deserves; and have its best interests represented in higher level meetings when it comes to self-service offerings.

2. Regular maintenance and consistency

Once a Knowledge Base is out there, it doesn’t stop. Knowledge Bases shouldn’t be stagnant but rather living and breathing products that receive improvements over time. Having a tech writer means they’ll observe patterns and trends from customers using the Help Centre, write missing topics that customers are contacting Support for, and rewrite documentation that doesn’t seem to solve customers’ problems.

It also means the tech writer is ensuring all information is uniform across internal and external channels for better adoption and more effective comprehension. As a bonus, your Support agents will be a lot more consistent in delivering the same information to customers who are also reading it in your Knowledge Base!

3. Research and development

Constant learning is key. Having someone dedicated to this full-time means not only improved, organized and grammatically corrected documentation, but also someone that can keep up with industry standards and best practices when it comes to Knowledge Bases. This will reap benefits in helping your Support team learn faster, and the investment in improvements will make your Knowledge Base stand out from the rest. If you want to be known for providing excellent self-service, a tech writer that can do research and development will go a long way in this goal.

4. Lower costs

Having someone responsible for maintaining your company’s Knowledge Base will help deflect cases from your support’s queue, especially when customers can self-service themselves and resolve their own issues. An effective Knowledge Base means support knowledge is available 24/7 globally, and allows your support agents to focus on complex cases and improve systems instead of getting caught up in repetitive basic questions. Less cases and less money spent is always a win-win.

5. Digestible information

In some roles, the information is complex and technical by necessity. But when your Support team is helping customers, technical information can be a barrier and a deterrent. Having a tech writer means they’re able to cater to nearly every reader, and can break down the information into accessible chunks for both your Support teams and your customers. Easy to understand information means less follow-up with customers and smarter Support agents. It also makes onboarding new agents and new customers that much more effortless when the information is documented and clearly explained by the tech writer.

6. Track, collect, and utilize data

Your Knowledge Base is an extension of your company (or its product), so it’s salient to use data and analytics to identify trends and gaps, make data-driven decisions to curate new content or update content. The data that is collected is like gold, because it gets the attention of decision makers, especially if it’s compelling and requires further investigation. This data can also influence further research and development opportunities, or help you persuade others to allocate resources towards continued improvement of your Knowledge Base.

7. Support support

This is one of the 8 values that my company FreshBooks’ Support team lives by, and when it comes to documentation, it’s incredibly crucial. Your Knowledge Base is essentially a library of your company and its products. Anybody from inside the company can check it out like a book for internal purposes, like educating new hires during their onboarding, and as a reference for your Support agents during their customer support calls or emails. Knowledge is one of the foundations that all Support departments rely on, and having a dedicated tech writer means a strong foundation to support Support.

Tech writers bring happiness and so much more

When Support folks have the documentation needed to become coveted veteran agents, and when customers can effectively self-service themselves using your up-to-date Knowledge Base, everyone wins epically.

Your Support team and customers will always need information, just like mine do. Be the knowledge hero they need — like how FreshBooks has its Batman.

If you've ever had to persuade someone to help maintain your company's knowledge base, or you're like me and already maintaining documentation, I'd love to hear what else you've learned. It's time we documented our documentation practice, so that we can all benefit from each other!

As tech writers, one of the key ways to make your documentation better is to make friends with people who have access to info you need, like Product Managers (PMs). Sometimes all it takes is to start a conversation first.

Organizing knowledge can be a lot like sheep herding cats — just downright difficult. Though this is something that most tech writers/documentarians deal with regularly, you don’t need to be one to clean up your documentation and keep it all in one place.

Not sure if you need to organize? Ask yourself whether your knowledge is scattered everywhere and hard to keep track of. Or maybe you and your team are running into situations like these:

• Veteran employees leaving along with their acquired knowledge

• Subject matter experts becoming sick or going on vacation

• People duplicating the same knowledge, not realizing another had already made it

• Onboarding new hires is slow, their learning curve nearly overwhelming

Or perhaps, you’ve stumbled across some undernets, an apt term coined by Jacob Touchette (source):

Undernets are the “non-formal and unintentionally walled off bits of knowledge that [folks] document in private”, also known as “rogue docs or sheets [others] create for themselves. These are often incorrect, out of date, or not shared with the entire team.”

Undernets are very real, and they can be a symptom of a larger problem: people don’t trust the knowledge they’ve been given, or can’t access that knowledge easily, so they turn to creating undernets of their own.

Ready to start organizing your knowledge? Here’s my how-to-guide, broken down below:

1. Collect the information and store it in one place

This is where you have to search far and wide to collect them all (like Pokémon). So round up all your coworkers on your team, and have them share their files and documents with you. Look extra carefully for those coworkers who hoard information like dragons hoarding treasure, so you can get rid of all undernets in one fell swoop.

When you collect information, store them in a central temporary place, or in the final home of where you’d like the documentation to live. Whether that’s your company’s Confluence wiki, Google Drive or Dropbox… you can copy and paste everything you collect in there, or upload files as you get them. Keeping everything in one location makes it easy to track what you have, and more importantly, what you don’t have.

2. Create a catalogue

Once you’ve shepherded all this information into one place, it’s time to catalogue what information is available to you and your team. The best way to do this is to create something resembling a Table of Contents:

Organize content by a particular category or theme, and you can even add sub-categories or nested lists underneath each as you catalogue every single item in your central repository.

3. Determine what’s missing

Now that you have your existing knowledge catalogued, this is where you start filling in the gaps with what’s absent or lacking. When you do this, distinguish the missing content you add in a different colour, or highlight the text, to indicate “needs more info”. You’ll flesh out the actual missing content in a later step.

Don’t be afraid to tap into your audience — your coworkers and stakeholders and anyone else who relies on this information will certainly have lots to share on what they’d like to see added and documented. As a bonus, if you use email regularly or chat apps like Slack, check your inbox and Slack channels for repetitive questions that often come up — use those questions as inspiration for content that can be created!

4. Test and build the information architecture

Information Architecture (IA), in case you’re not familiar with it, focuses on organization, structuring and labelling content in an effective and sustainable way. This helps readers find information and complete tasks — like finding your documentation!

Look at your catalogue from an IA perspective — does the way you’ve organized content makes sense and is easily findable? Or is there room for improvement in where the information is ranked?

If you’d like to user test your IA and see if it’s effective, I recommend doing a Card Sorting exercise, which is a common UX Testing Tool (Google has a great book on it here). Put some of your coworkers through this exercise with your catalogue, and see if they rearrange it into an order that’s identical to yours or you may find yourself being surprised.

Running through one or more card sorting exercises will help inform the final IA design of your catalogue from the feedback and analysis received.

5. Tidy up your content

This is the fun part — the meat and potatoes of the process. If you’ve been storing the content in a temporary place, you can start moving it into its new final home. If your content is already where you want it to live, then you can start by reorganizing the structure according to the new IA/Table of Contents you’ve put together in step 4 above.

Then you’ll want to ensure a copy of your IA/Table of Contents lives as the landing page of this central place, or is readily available in this central place. All visitors can reference your Table of Contents as another wayfinding tool for looking up information (or to see what’s available). By the end, your content should look consistently formatted, and be structured in the hierarchy you’ve crafted.

6. Share the news and update regularly

Now that all this knowledge is centralized in one place, share it with your coworkers, stakeholders (like your Product Managers) and anyone who requires access to it! This will help prevent any new undernets from forming and increase the value of your knowledge.

To ensure your investment in this does not go wasted, make sure this central repository of knowledge stays updated. Whether that means folks take turns cleaning and updating the documentation, or a sole person takes it on — add new information as it gets created, groom all your existing content, and don’t be afraid to delete it if it’s no longer useful.

From start to finish

If you’ve followed this process, you’ll now have one source of truth for your documentation and one central place to direct people to. Knowledge is only treasured if it continues to be valuable to others, so maintenance is key to its success and to your return on this investment of your time and efforts.

And hopefully your new centre of documentation is something that you and others can be proud of (or in the words of Marie Kondo, it brings you all joy!).

Do you have a triaging method that works best for you? Feel free to share your process here, so we can all learn from each other’s documentation experiences!

As tech writers, one of the key ways to make your documentation better is to make friends with people who have access to info you need, like Product Managers (PMs). Sometimes all it takes is to start a conversation first.

Whether you work solo like Batman or in a team, it’s helpful to get all the PMs you work with to understand both what you do and what you need from them so that everyone works effectively. This is because often in typical Agile environments, PMs are the primary communicators of their team’s deliverables, which makes them an excellent resource for tech writers like myself.

When I first started chatting with the PMs at my work, I didn’t begin anywhere in particular, but over time, I’ve been able to organize my thoughts into these useful talking points below. Use these points to make friends with your PMs: 

Start with the dream

Put the PM in your shoes by helping them understand what the process of documentation would look like in a perfect world. Walk them through the genesis, iteration and implementation of a docs cycle. This is where you can gush over how amazing it would be to get detailed documentation in a timely manner, or ahead of schedule, including supplemental information that you didn’t have to ask for. Dare to dream of being able to publish with no delays and even better, with no last-minute scrambling to make crucial edits. 

Don’t forget to sweeten the dream by reiterating the benefits of documentation - it yields a smoother product rollout, more informed customers and better engagement with your product. All good things that will make your PM swoon with joy too.

We wear many hats

While writing may be explicitly called out in some of our job titles (or in my case, “Communications”, which is similar), our work isn’t just exclusively limited to writing. I like to offer a gentle nudge to the PM that I wear (too) many hats (just like them!). I’m also a data analyst, graphic designer, project manager, self-learner, subject matter expert, and trainer… just to name a few. Creating content is only a small part of it, and it’s key to dispel any myths that your PM could be inadvertently thinking of in your role. Use this opportunity to bond over any overlapping similarities, especially if they have deliverables that can save you from putting on one of your many hats too. Don’t forget to tip your hat(s) off together to a the start of a beautiful collaboration.

Product equals content

PMs are tasked with the goal of ensuring the product is delivered. This is where I remind the PM that documentation is absolutely a part of the product and not a separate entity. Product cycles are very similar to documentation cycles, so I like to describe my documentation workflow and how much time I spend on researching, synthesizing and editing to produce the final result. Draw the connection between all stages of your cycle so the PM can understand why you’re depending on them for certain deliverables. If the PM wants to see the product successfully launched, help them understand why knowing the edge cases and unhappy paths is useful for internal documentation, and why the happy path is useful for external-facing documentation.

Timing is everything

Establish expectations around when you need information from others. Documentation takes time, like anything else in product development. So if a new feature ships at the end of week 6, and you need at least a week to prepare, the PM should understand that you need to have information no later than week 5… not on Thursday of week 6. The more explicit you are about scheduling expectations, the more headaches you avoid, and the more likely you’re able to publish the documentation on schedule. This ensures the product rollout goes smoothly with no disruption in information to your customers.

Set up a channel of communication

Documentation doesn’t appear out of thin air with zero input, and collaboration is key to getting information. So work together with your PM to determine the best way of communicating, whether that’s by Slack, email, Google docs, or an unladen swallow. Whatever the channel is, use it to acquire whatever you need to complete your documentation (like access, files, input, screenshots and more). Knowing the best way to communicate with the PM is also useful if you have questions, especially when it comes to extra information and product status, even more so if it’s unexpected.

… and make it the start of a beautiful collaboration.

If you cover these talking points, you’re off to a great start. Once PMs truly understand your role, capabilities and product needs, the more likely your PMs will be responsive, proactive and communicative. Share some fist bumps knowing that your product also has effective documentation to go along with it.

If you’ve got a great groove going with your Product Managers, I’d love to hear what your secret ingredient is. It’s time we documented our documentation practice, so that we can all learn from each other!