Technical Writing

What Is Technical Writing

Technical writing (sometimes written as tech writing) at its base is a process of information and knowledge sharing. Since you are not the only person working on A with only your hand-created tools, everything today requires enough info. New library in your project? What does this function does again? How can we fetch this resource? Do these questions sound familiar? In the team, you would go to the person who wrote questioned software and be like Hey, Prokop, how does it do this?. But teams get more extensive and more remote. The person who wrote that particular piece of code is probably working on something else (and can be living 10 hours in timezones away from you). Synchronicity becomes a problem. You want your answer now, or the project burns money. It is frustrating to sit and wait for just enough information.

If everyone worked like that, nobody would do anything, ever. The knowledge debt would creep back and back. So, how to fix this? You can turn the single-person resource into multiple people. Somebody probably worked with that code, so you don't need to ask Prokop; you may ask Adéla. But time is ticking. She is also working on something important right now. So what now? That is when technical writing comes to the rescue.

The text itself is asynchronous. Well-documented software answers almost all questions leaving friction and frustration at bay. Text can be anywhere in the world, at the same time. It doesn't work on something else.

Source: Technical Writing

Technical writer facilitates this process of technical sharing. With sharing, they enable collaboration. Moreover, a skilled tech writer goes even further. They design how to share the information. They entangle a mess, find what is relevant, and share it. Imagine working with a completely new tool on your new project. The amount of stuff unknown is frightening. Tech writers job is helping you get from the zero-point to the hero point. You don't need all details from the start. Too much information can overload you and demotivate you.

Why You Might Want Technical Writing

Usually, you may understand Technical writing through documentation. In short, documentation is a tool that simplifies information sharing. Tech Writer is the one who is responsible for creating and owning documentation. They keep information up today, are responsible for content quality (see Documentation testing). Good documentation makes your product better.

But that is not all Tech writing can do. Together with the UX team, he can help with Labeling, Descriptions, and more. If you have experienced TW, their insight can improve your UX strategy. Tech writers should know how people learn. And that is always important for newcomers.

Good tech writer learns about information. They look at how to communicate effectively with readers. If you have their inside while designing a new product, you can increase the chance of success. They can interview. They know where to get what they need.

Other significant things Tech Writing does are:

• Improvements to DX
• Improvements to Developer Acquisition.

A good tool - if it is API, SDK, whole Dev Portal, or a software product, needs to have documentation. You are building a relationship with the developer through how easy it is to use your XYZ. In the end, you are helping your new friend in your software neighborhood.

Problems Technical Writing Helps to Solve

• Bad product-market fit
• Unsuccessful product
• Unhappy clients
• Disconnect Between Business and IT
• Bus Factor
• Demotivated Team

How to Implement Technical Writing

The best way is to have someone interested in technical writing in your team, preferably a skilled tech writer. But not everyone has the resources for it (and for the UX team and others).

So, if you don't have a technical writer in your team, you should want to start understanding the field more. Start with documenting your work. Imagine you have a fresh start (you can always relive the memories by doing something completely different. Switching tech stacks doesn't count since you have general information about coding. Try cooking, for example.). What do you need now?

Start writing about the first steps with A. Guides, tutorials, or How-to give enough to play. Look into writing resources - Google has a free technical writing course. Look into tools that could make your life easier. Automate. Use Style Guides, like Microsoft Writing Style Guide, Chicago Manual of Style or the University of Oxford Style Guide, Google developer documentation style guide or English Style Guide - European Commission.

You want to be clear in your writing. To avoid friction, consider switching to Simplified Technical English. Play with the language, watch your information.

After writing the first steps, look into your code. Yes, a good code should be clear enough to have almost no documentation. But there is stuff you won't express only in code. Things like business logic or architecture are unclear on the first sign. And then the issue of knowing where to look. Should I find my foo in bar or barbar? Where should I start when I want to contribute?

Not only that, but comments can make your short function into a long beast. Consider moving them outside of the code. Why does A return B? What is the logic of this function. Usercode - what is this variable?

• Is your API understandable outside your dev circle?

While at it, you can think about information. Ask yourself:

• How do you make sense of things?
• What helps you to understand?
• How can I make the information more accessible?
• Am I telling just enough?
• Is this understandable?
• How can I communicate better?
• Is this the best way to say it?

Common Pitfalls of Technical Writing

• Not enough tech writers.
• It can be hard to explain why good information sharing is important.
• It is hard to write.
• Developers are forced to write. They usually don't like it, and it's wasting their time.
• Tech writer wasn't given time to understand the context or is not technical enough to understand its audience.
• The Curse of knowledge - writer already expects information for granted.

Resources for Technical Writing

• Google Technical Writing resources
• HOW TO MAKE SENSE OF ANY MESS by Abby Covert
• The curse of expertise: The effects of expertise and debiasing methods on prediction of novice performance.