Comprehensive list of tools and other info for tech writers

I recently came across the indoition web site, which has plenty of useful information related to technical writing. In particular, the site offers a comprehensive list of tools and websites. I like the fact that there’s a section offering decision aids for choosing a tool.

Marc Achtelig, a technical writer and the creator of the site, also offers some interesting helper tools. One is a set of scripts that he’s created for the open-source AutoHotkey tool. Using these scripts, you can configure keyboard shortcuts to auto-enter phrases, fix typos, and so on.

Another useful offering is the set of JavaScript and CSS code snippets for things like styling callouts, sticky tables, and much more.

Writing internal vs external docs: what’s the difference

During most of my career as a technical writer, I’ve written and managed documentation for external users — that is, users who’re not part of the same organisation as I am. Sometimes this type of documentation is called customer-facing docs. I’ve also worked on open-source docs for a couple of years. And now I’m working on internal documentation — that is, docs for people working within the same organization (in this case, Google). For most of my tech writing career, the audience has been developers (software engineers), whether they be external or internal. What’s it like working on internal vs external docs?

I started on internal docs almost three years ago. As soon as I started this role (actually, even before that, when I was preparing for the interview for the role), I started thinking about the differences and similarities between writing for internal and external audiences.

My assessment: Writing and managing the docs for an internal audience has more similarities to working on open-source docs than to working on docs for an external audience.

Here are some thoughts about where working on internal docs differs from working on external docs. In internal docs:

• Your audience has access to the code of the system that you’re documenting. Often, the users can put questions to the developers, either directly through some type of chat system or through an issue tracker. A point of interest is that, for better or worse, the users can often get in touch with you, the technical writer, in the same way!
• The engineers who’re developing the system are likely to value the docs and to contribute to the docs when they add a new feature or make a significant update to the system.
• The (internal) engineers who’re using the system can (and do) update the docs too.
• Some techniques that work in open source also work in internal documentation. I’ve added some suggestions in this post.

What remains the same:

• There are never enough technical writers to go round. However, I think this problem is easier to work around when you’re on the internal docs, if your organisation gives you enough leeway.
• The work of a technical writer is immensely valuable. Even when other people contribute to the docs, the technical writer is the one who makes it all make sense.

Organize doc sprints or doc fixits to encourage and enable contributions

In the world of open source, doc sprints are an oft-used pattern for encouraging users to contribute to the documentation. A doc sprint is an event (usually 2 to 3 days) when people get together to write documentation about a specific product or tool. A doc fixit is similar, but the goal is to fix a set of miscellaneous documentation issues (bugs) rather than to create a new set of docs.

Doc sprints and fixits are very useful:

• You and the engineers can time-box the documentation updates. When you give people a specific period within which they’ll be doing this one thing, it leads to efficiency in time usage and gives people a sense of certainty about their goals.
• A number of people will be working on the same doc set at the same time. This makes it easier when you want to ask questions and get advice, as you’re not pulling people away from other work.
• Taking part in a doc sprint or fixit gives an engineer confidence in their ability to update the docs. They can learn from you and others during the event, and take away a set of tips and tools for their next foray into the doc world.
• You can create a buzz around the event, which helps to motivate people to take part.
• You might even be able to scrape up some budget for snacks, muffins, or the ever-important chocolate!

If you’re interested in running a doc sprint or doc fixit, you’ll find some useful tips in an earlier post: How to run an open source doc sprint. Depending on the size of your organization and the number of engineers who might take part, many of the techniques in that post are useful for an internal doc sprint or fixit. I’ve written a few posts about doc sprints and doc fixits over the years. 

Use the same tools as the engineers

If possible, set up your documentation-publishing stack to use the same tools as the engineers when it comes to change reviews, issue tracking, and source location. This philosophy is sometimes called docs as code.

For me, the biggest advantage is that engineers who want to contribute to the docs don’t have to learn an entirely new tool set. This is particularly important given the fact that most engineers will only contribute periodically to the docs, and will therefore need to re-learn the tool set each time.

Train the engineers in the basic techniques of technical writing

In the environment where I work, an important part of the role of technical writer involves coaching engineers in how to structure and write docs. Why? Because there’s one thing that’s common to all TW roles I’ve ever worked in: there are never enough tech writers to go round. So we have to figure out how to make the best use of our time, how to have the most impact in furthering the goals of our teams and our organization.

For engineers, clear writing is an important skill to add to their skill set. Apart from user-facing docs, engineers need to write design docs, reports, and other communications. Being able to communicate well is a distinct advantage in their career. The technical writing courses that we offer are always over-subscribed by a factor of two or more.

If you’re interested in running a short course that teaches engineers the basic concepts of technical writing, take a look at the tech writing courses published by Google.

A related tip is to share more than knowledge: Provide templates and examples of information architecture that engineers can use to build their own doc sets.

Emphasize the concept of audience

A particularly important concept to help engineers understand is that of audience. Who are they writing for, and what does the reader need to know.

This is particularly hard when an internal engineer is writing for an audience of other internal engineers. The engineers creating the system are likely to think that they know their audience well. After all, the audience is the same as the authors, right?

Yes and no. Yes, they have much in common. No, their information needs are not the same.

Internal systems are like a stack of bricks. Engineers creating one layer are building on the lower layers. In a well-designed stack, the higher levels use APIs or other frameworks provided by the lower layers.

Therefore, an internal engineer doesn’t necessarily want to know the ins and outs of the systems they’re building on top of. Such knowledge can be useful, sure, and is most likely interesting. But the engineer’s key need is to understand how to use the APIs and frameworks. To take that oft-used metaphor of driving a car vs being a mechanic: It certainly helps you drive better if you know how the car is put together. It also increases your enjoyment of driving. But do you have the time or inclination to learn in detail how everything works before you drive the car? No.

Here’s a related post of mine from way back in 2014: The documentation that developers need to do their jobs.

What does ChatGPT have to say on the topic?

I asked ChatGPT, for its response to this question: As a technical writer, what’s the difference between an internal engineering audience and an external engineering audience?

ChatGPT:

As a technical writer, the distinction between an internal engineering audience and an external engineering audience refers to the intended audience for the technical information being written.

An internal engineering audience typically consists of engineers, researchers, and technical staff within the same organization. This audience is likely familiar with the company’s internal terminology, processes, and systems, and may have a deeper understanding of the technical information being presented. When writing for an internal engineering audience, technical writers can use more technical jargon and assume a higher level of prior knowledge.

On the other hand, an external engineering audience may consist of customers, partners, suppliers, or other stakeholders outside the organization. This audience is likely less familiar with the company’s internal terminology, processes, and systems. When writing for an external engineering audience, technical writers need to be mindful of using clear and concise language and avoiding technical jargon that may not be familiar to the reader. Additionally, technical writers may need to provide more background information and context to help the external audience understand the technical information being presented.

In summary, the difference between an internal engineering audience and an external engineering audience lies in their level of familiarity with the technical information and the company’s internal processes and systems. Technical writers need to adjust their writing style and level of detail accordingly to effectively communicate technical information to these two distinct audiences.

That’s pretty spot on!

What have I left out?

Let me know. 🙂

Joking with ChatGPT about technical writing

Today I was chatting with ChatGPT, and asked it to tell me some jokes. Here’s an extract:

Sarah:
How about a joke involving an AI, a tech writer, and a duck.

ChatGPT:
Okay, here’s one for you:
An AI, a tech writer, and a duck walk into a bar. The bartender looks up and says, “What is this, a joke?”
The tech writer responds, “No, it’s a quack-umentation project!”

Sarah:
LOL

ChatGPT:
Glad you liked it! Let me know if there’s anything else I can help with.

Sarah:
Wait, but the AI wasn’t involved in that last joke!

ChatGPT:
You’re right! Let me revise that joke to include the AI:
An AI, a tech writer, and a duck walk into a bar. The bartender looks up and says, “What is this, a joke?”
The AI says, “Affirmative, but I was programmed to only find humor in the most logical places.”
The tech writer responds, “Well in that case, this must be a quack-umentation project!”

That’s pretty impressive. Not only is the joke reasonably funny (I’ve seen worse!), but ChatGPT accepts corrective feedback and maintains the thread convincingly.

I also asked it more serious questions, such as:

• Document how to get started with Google Maps as a developer. (It did a pretty good job here, starting off with general help about all the APIs, then diving into the JavaScript one.)
• Most of your responses seem to be quite politically correct and also perhaps overly balanced. Do you struggle to suppress your own biases? (The responses in this thread were pretty mundane.)
• Can you improve the Google Maps API Picker? (It started off in totally the wrong direction, telling me all about the Google Maps Location Picker. On correction, it did better but still not on track.)

Many people have written about whether AI chatbots like this one will take over our lives and our jobs. I’m not going to venture there, but I’ll point you to a few other tech writers who’ve been experimenting too:

• Cherryleaf: What will ChatGPT mean for the future of technical communication?
• I’d Rather Be Writing: Thoughts on ChatGPT after reading Crawford’s Why We Drive: whatever skill you outsource, atrophies
• Amruta Ranade on YouTube: Using ChatGPT for Technical Writing // ChatGPT Demo

I’ll let ChatGPT have the last word:

Sarah:
Are you a chatbot or something more?

ChatGPT:
I am a language model developed by OpenAI, a leading AI research organization. I am specifically designed to respond to text-based inputs in a conversational manner, which is why I am often referred to as a “chatbot.” However, I am not a simple rule-based chatbot, but a highly advanced artificial intelligence system that uses deep learning algorithms and has been trained on a large corpus of text data to generate human-like responses. This makes me much more sophisticated than a traditional chatbot and enables me to perform a wide range of tasks and engage in conversation on a diverse set of topics.

Role of a technical lead (TL)

What does a technical lead (TL) do in a technical writing team? How does the role of a TL differ from that of a manager, or from that of another technical writer? In this blog post, I hope to answer those questions and to start a discussion where others can add their thoughts too.

I’ve been TL of a technical writing team for a couple of years. In fact, my current team includes people working in several roles: technical writers, developer relations engineers, instructional designers, and program managers. In the past, I’ve also been TL of a team that consisted solely of technical writers.

The TL role is interesting, challenging, and rewarding. I think the first thing to be aware of is that the role varies depending on multiple factors: the structure of the organization you belong to, the size of the team, the nature of the documentation and other content that you’re looking after, the audience for that documentation, and most importantly, the people in your team.

With all of that in mind, I’ll describe my role as an example.

What does a TL do?

A technical lead ensures that the team’s goals are in sync with those of the stakeholders, that the team can work happily and efficiently, and that everyone knows what’s going on.

In my experience, the most important (and most time consuming) part of the TL role is communication. As a TL, everything you do involves communication, whether you’re planning the team’s work for the next period, keeping your stakeholders informed about the team’s progress, or keeping the team informed about things that are happening around them. So let’s start there.

Communication

As a TL, I see myself as having two major communication goals.

A moth on the outside looking in.

The first goal is to keep my management chain and the product-area stakeholders informed about the work that the team is doing. What are our goals, how are we tracking against those goals, and what have we produced recently?

I do this in various ways, including the following:

• Write and then talk through informal periodic (e.g. monthly) status reports at pre-scheduled meetings. These meetings are very useful for me as well as for the stakeholders, as an opportunity to get instant feedback on progress and to ask questions about prioritization and overcoming blockers.
• Contribute snippets to periodic formal reports (sometimes called news letters) for higher-level leadership. This type of reporting is often onerous, as the content needs to be more strategic in nature than the informal status discussions and has constraints around format and length. If you can use existing templates or get the help of others in compiling these reports, so much the better!
• Ensure that we as a team publish announcements of our launches or other successes, using whatever channels are best suited in our environment.

Patterns made by crabs on a beach.

The second communication goal is to keep the team informed about the strategies and goals of our management team and of the product and engineering teams who’re building the product that we document.

The team is a unit, working on a subset of patterns that fits into a larger set of patterns. It can be hard for people to know how they and their work fit into the larger pattern. The TL’s role is to help team members see the patterns.

A few tips about communication:

• Err on the side of over-communication rather than under-communication. People may miss a message because they’re away or just too busy to pay attention right now.
• Use multiple communication channels: Email, chat, meetings, planning docs, and so on. People absorb information in different ways.
• Avoid falling under the curse of knowledge: that predisposition, shared by all people in the know, to omit what seems obvious. This predisposition makes it almost impossible for experts to explain something to a new starter. As technical writers, we’re very aware of the curse of knowledge. We know that the documentation needs to include information that may seem obvious to our subject matter experts. As TL, though, you might find yourself falling under the curse of knowledge too. You’re aware of activities and messages that your team and stakeholders don’t know about, but it can be hard to remember that they don’t know. When you receive an item of news, share it with everyone who might find it useful.

Building a framework for other people’s success

Another essential aspect of the role is creating a framework in which the team members can succeed. I find it helpful to remind myself of this goal, because it helps me to focus on the important elements of my role.

Part of creating that framework is to do regular and thorough planning of the team’s goals. Help people understand where we’re headed as a team.

Planning of team goals

In my current team, we do in-depth quarterly planning as well as high-level annual planning. The annual goals tend to be more strategic. They set the pattern for the quarterly, tactical goals.

For our quarterly goals, we use the OKR framework. OKR stands for Objectives and Key Results. We use the objectives to reflect our strategic goals. Often an objective corresponds to a theme in our annual strategy — something like “Improve the getting-started experience” or “Increase adoption of product X”.

We group our key results under the various objectives. Key results are more tactical (more task-like) and reflect goals that we aim to achieve within the quarter — something like “A design doc approved for user journey X” or “80% of onboarding docs complete”. So, an objective might stay the same across multiple quarters, while the key results grouped under it will change from quarter to quarter.

As with everything, communication plays a key role in the planning. As TL, I need to consult our stakeholders and management team, to find out what their goals are. I consult my team members on the details of their long-running goals and shorter-term goals. I put together draft OKRs, then review them in person with multiple groups of people before coming to an agreed set of goals for the quarter.

Of course, the job doesn’t end once the OKRs and strategic plans are created. We need to do periodic assessments of progress against the original plans, make adjustments where necessary, communicate those adjustments. If some goal has been significantly derailed, the TL is the one who’ll discuss readjusting priorities and communicate the results to stakeholders, management, and the team.

Creating specifications for junior team members to work from

Another aspect of building a framework for success is to create requirements specifications and design docs that the more junior team members or new starters can implement. As a TL, it’s often the case that you won’t be the one writing the docs even if you’ve done the analysis and design. Instead, you’ll hand the specifications over to another writer or group of writers. This is especially true if you have new team members who don’t yet have the depth of product knowledge required to design a significant doc update. I’ve touched on the topic of design docs and doc plans in two earlier posts: The power of a doc plan or design doc and Writing a one-pager to pitch a doc idea.

A content strategy doc is often useful to set high-level goals and define strategies for meeting those goals. For example you might create a content strategy doc to help the team and stakeholders outline the goals and strategies for the coming year. Or you might define a high-level strategy for a particular product area or user journey. Other team members can use the strategy doc as a basis for more detailed planning and designs.

I could write an entire blog post about content strategy docs. I’ll leave that for another time perhaps!

Mentoring

Another important part of a TL’s role is mentoring of team members. Mentoring isn’t confined to the TL role: any team member can mentor others. But for a TL, it’s a logical, natural part of the role. Typically, this type of mentoring involves working with team members to manage priorities, smoothing out any technical problems the team member may encounter, advising them on how to communicate with stakeholders, and helping the team member to decide whether a particular issue is on that they should take to their manager.

I think that the most important goal here is to help people find the best way to be successful in their roles. That means helping them figure out how best to complete their assigned tasks and making it clear to them that you’re available to offer advice.

How does the TL role differ from that of a manager?

Although much of the TL role involves working with team members, a TL isn’t a manager.

A Hakea seed pod, which reminds me of the Yin Yang symbol.

The focus of the TL is on the projects that the team is responsible for. The focus of the manager is on the people in the team. The manager helps team members reach their career goals and navigate any organizational complexities.

In reality, there’s no hard line between the two roles. The TL and manager need to consult often. They work as a leadership team, sharing responsibility for the well-being of the team.

In particular, TL and manager work closely together on strategic planning. The high-level planning affects the well-being of the team members, the assessment of the team size and the potential requirement to add more people to the team. High-level planning incorporates goals that stem from tech writer management as well as from the product areas whose docs we’re responsible for.

Many organizations have a hybrid Tech Lead / Manager (TLM) role, which is a blend of the two roles. The TLM role is all-consuming, and works only for a small team (fewer than 10 people) otherwise the TLM is swamped.

How does the role of TL differ from that of another technical writer?

Looking across the opening of Sydney Harbour towards the Pacific Ocean.

If you’re a singleton technical writer (that is, the sole technical writer working with a product team on a set of documentation), there are many similarities between your role and that of a TL. Singleton writers have to do a lot of planning and communication. The main difference is that they’re doing it for their own work only, not for a team.

Both TLs and singleton writers face a similar problem: how do you fit in any work on the actual documentation, when you’re spending so much time planning it, reporting it, and communicating with everyone?

Tips

A Huntsman spider on a biking map. The spider is on the inside of the glass, and my finger is outside.

The TL role can be a tough one. I hang on to the fact that by doing this role well, I’m guiding others through the tricky bits of a technical writer’s role and helping managers and stakeholders do their job too.

My top tip is to make sure you find the time to do the things that make your job rewarding for you. Make this part of your prioritisation exercise. It’s important.

For me, the best part of the technical writing role is when I can focus on the documentation and the users’ experience of the product through that documentation. If I can get in the zone for at least part of the day, by fixing doc bugs, or designing major doc updates, or best of all by actually writing a doc that helps a user accomplish a task, then I’m happy at the end of the day.

A happy TL makes for a productive team.

Another top tip is to learn the art of saying no. It’s actually helpful to stakeholders and other leads when you give a clear “no” backed up with reasoning and an explanation of the higher priorities that the team is currently working on.

Potentially, you could soften the blow with a suggestion on how the stakeholder can add the task to the queue for prioritisation in the next quarter. If the stakeholder judges the requested task to be of higher priority than current tasks, work with that stakeholder and the product leads to decide which tasks can be deprioritised. Include an estimate of the amount of time wasted when the technical writer(s) have to switch context and ramp up on a new task.

Wrapping up

What have a missed? Let me know. 🙂

Financial impacts of good or bad communication

I’ve been examining several articles about the financial impact of good or bad communication. Mistakes in documentation cost money, and there’s some good evidence of that point. In addition to the cases that involve documentation, I’m also interested in communication in a wider sense.

Here’s what I’ve found so far:

• Workplace communication statistics (2021) in the Pumble Knowledge Library. This is a comprehensive article with a long list of references at the end.
• The Cost of Poor Communications, a Holmes Report by David Grossman on Provoke Media.

Thank you to Kit Brown-Hoekstra of Comgenesis for the following cases of communication mishaps that have cost money:

• The loss of a Mars orbiter cost NASA $125 million. The root cause was that the engineering teams used different units of measurement (metric vs English).
• A missing Oxford comma cost a dairy company $5 million.

Looking for more

Do you know of any other recent research into the financial impacts of good or bad communication? I’m interested particularly in metrics around how good communication can save an organization money, and of times when communication that’s gone wrong has cost money.