Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users

Dashboard
Notifications
Mark all as read
Q&A

Technical Writer Skill Set

+4
−0

As technology and industry demands evolve, what tools/skills should one focus on learning/improving as a technical writer?

Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

0 comments

2 answers

+4
−0

Some core skills for a technical writer are:

  • Ability to communicate effectively in writing.
  • Ability to understand the subject matter (what you're documenting) from the user's perspective, including the user's needs.
  • Ability to understand the subject matter enough to reason about its behavior.
  • Tools of the trade.

(I'm leaving out the stuff that applies to professional development in general -- collaboration, planning, task-switching, etc.)

Communicating effectively in writing

For a technical writer this almost goes without saying, but I'll add some things to the "duh" baseline. Effective communication, particularly in technical documentation, requires more attention than you might think to language, concision, and structure. Word choice is important, particularly consistency in terminology -- different terms will lead some readers to think you mean different things.

Technical writers new to the field, in my experience, often err on writing too much. If two examples are good then four are better, right? Only if the new ones demonstrate something different -- an edge case, an error condition, etc. Similarly, more words are helpful if they add meaning and don't obscure the essentials, but can get in the way if you're not careful in how you structure the documentation. Think about the differences among task documentation, reference documentation, and conceptual documentation -- all are important, but be mindful of mingling.

Understanding the user perspective

I had a coworker once who had a sign on the wall above his monitor. It said "I am not the user".

You are not the user (probably). You are writing for users who are database administrators or electrical engineers or programmers or soldiers or car mechanics. The people who built the product you're documenting probably aren't the user either, so while we also need to seek information from them about how the thing works, they're going to give you an "inside" view most of the time. Always look for the people in your organization who are closer to the users and work with them too. Unless you're lucky you probably won't be able to talk with actual users (or not very many), so cultivate the skills to research this from a slight distance.

That's the baseline, but it's even more valuable if you can bring the user perspective to design discussions and interface reviews. For this, it's helpful to learn both the basics of the domain you're working in and some general principles of user-centered design. Also, you can apply user-centered design to your documentation, not just to the products you're working on.

Any particular domain -- databases or car engines or Java APIs or whatever -- might last only as long as your current gig. (The more general, the more likely you'll be able to reuse, but your next job might be in a completely different domain.) The key tool isn't the knowledge but the ability to gain the knowledge -- research skills, experimentation (can you use the product?), finding and working with the user-facing people in an organization, and even sometimes reverse-engineering support tickets (the user asked for X; why?).

Understanding the domain

This point overlaps the previous one, but is more inward-focused. The more you understand about how what you're documenting is built, how it behaves internally, how it integrates with other pieces, etc, the more effectively you'll be able to both anticipate issues and dig out information the developers didn't think to give you. As with the previous item, the career enhancer isn't so much the specific knowledge as the ability to get it. Some of this will come from using the product, some from reading specifications, some from discussions of bugs (you can learn a lot when a developer explains why that happened), and some by learning about the domain in general.

Curiosity, channeled well, is a useful skill for a technical writer.

Tools of the trade

Job descriptions often list specific tools and technologies. I don't know why; any particular tool will almost certainly have a lifetime shorter than your career. But certain categories of tools and technologies are important to understand:

  • documentation development environments; the good ones are like software IDEs, but for writers instead of programmers

  • documentation source formats; even if your tool gives you a WYSIWYG editor, it's helpful to look at the source (today, that's probably some XML flavor)

  • documentation delivery, especially if you're delivering documentation online and can use CSS, client-side code, integrated search, etc

  • source control

(This answer is based on my observations from 30+ years in the industry, specifically software documentation.)

Why does this post require moderator attention?
You might want to add some details to your flag.

1 comment

Thank you for the very detailed response Monica. It is so easy to get caught up on the knowledge instead of leveraging the skills that help you gain that knowledge. Same goes for tools of the trade. Often I see that a company will require MadCap Flare, Dita, Oxygen, etc. But you are absolutely right; they will be replaced with something new before we know it. Thank you for sharing the categories; they are not emphasized enough, if at all. This is super helpful and much appreciated! yashikaissrani‭ 5 months ago

+3
−0

Monica covers the main points excellently. Beyond that, if there is one specific thing I would suggest that you do to improve and remain relevant as a technical writer, it is learning to code.

This is not about reading source code (though that is a useful skill in some jobs) nor about writing code yourself (though you won't learn unless you do), it is because everything these days runs on software. There will be code in almost everything that you will document. And the reason it is useful to know how to code is that it will help you ask good questions of developers so that you don't waste their time, and so that you more readily understand their answers, and the way they think.

Developers are critical path on every project, so you will get more respect and be more valuable if you don't waste their time. And they will be more willing to give you the time you do need if they respect you and feel you have done your homework before you ask your questions.

You certainly don't need to know how to code to have a tech writing career, but it will open additional doors, and, beyond the basics that Monica mentions, it is one of the best things you can do to stay relevant and enhance your career.

Unless you have a reason to choose something specific, the language to learn on today is probably Python. But don't think of it as learning Python. Think of it as learning to code using Python. And no, learning HTML is not learning to code.

Why does this post require moderator attention?
You might want to add some details to your flag.

1 comment

Thank you for sharing! I have definitely heard of this one a lot. Good to know that Python is the way to go. Thanks for the insight! yashikaissrani‭ 5 months ago

Sign up to answer this question »

This community is part of the Codidact network. We have other communities too — take a look!

You can also join us in chat!

Want to advertise this community? Use our templates!