Technical Writer Skill Set
As technology and industry demands evolve, what tools/skills should one focus on learning/improving as a technical writer?
2 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
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.
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.)
0 comment threads