What is the best way to learn technical writing?
I have a moderate level of skills in technical writing (TW) having gone through graduation in engineering. I was wondering what would be the best way to sharpen my knowledge. I am also interested in asking this especially for my juniors who have an opportunity for a fresh start.
Do we learn TW by:
- getting a good text book and reading it? There are so many of them; which one should I choose?
- taking a class and doing the homework?
- reading technical articles and imbibing their style?
- writing and referring to textbooks occasionally?
Sometimes, I find students and colleagues that do not have good technical writing skills i.e. they lack conciseness, clarity and completeness. I also do not adhere to this sometimes. So how do you improve your technical writing skills when you have already learned the "wrong" way. I want to let my students focus on that and at the same time help my colleagues. You may suggest me a book or some specific guidelines.
This post was sourced from https://writers.stackexchange.com/q/5341. It is licensed under CC BY-SA 3.0.
3 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.
My background: wanted to be a programmer, entered a math program in college (because that was how you got to CS), loved the CS but hated the math, switched to technical writing and took the CS from there, and ended up doing a mix of programming, tech writing, and software design for the next (cough) years.
Classes and books, even reading good examples, will only get you so far. To really learn to do technical writing, you need to write and get feedback. I still remember a senior developer once lecturing me (fresh out of school) on the changed meaning of a misplaced "only". Nit-picking details matter, and the best way to grow is to get nit-pickers to review your work. Since most people don't have time to do that out of the goodness of their hearts, you need to seek assignments that involve writing -- requirements specifications, interface design documents, detailed design docs, perhaps user stories, configuration instructions, and so on. If you can arrange to do some of this as part of your job, writing needed internal documentation that your coworkers care about being right, take that opportunity.
Doing that will teach you to write what your peers like to read, but how do you know if it's good in the abstract? That's why you also need to review examples from elsewhere. Pay attention to, say, the API documentation you're working with as a developer. What's good about it? What questions doesn't it answer? What does it say that makes you say "duh, tell me something I don't already know?" Observe what's there, what's not there because it doesn't need to be, and what's not there and leaves a gap. Look for patterns. (For example, many newcomers to API documentation write function descriptions that repeat what's in the signature. You already know the type of the return value; what does it mean? When can it be null? Are there error codes?)
(I'm using programming examples because that's my field, but the same process applies to any technical area.)
Yes yes, the basic English stuff matters too -- grammar, punctuation, consistency, and so on. Precision will matter more than in other writing domains. You should follow a style guide for the sake of consistency. And some aspects of technical writing require specific learning and practice, such as indexing. But what I've outlined in this answer provides a good foundation.
0 comment threads
Personally, I'm heavily in favor of #3 as a way of learning anything and everything to do with writing. I too spent several years studying engineering and have done my fair share of technical writing. If you're not a horrific writer to begin with, I feel you should have no trouble picking up the style and voice of technical writing by reading it.
However, I should note there is a little more to it than that-- you can imbibe the style just by reading it a lot; it'll get in your head. But the content you can't get subconsciously, not as easily anyway. You need to actively think about what you're reading. Why were the report's components placed in the order that they were? What did the author treat in depth and what did they gloss over? How did they start, and how did they conclude?
Once you know the voice of technical writing, understanding questions such as these will tell you what to say with it.
This post was sourced from https://writers.stackexchange.com/a/5342. It is licensed under CC BY-SA 3.0.
0 comment threads
The key to good tech writing is not style. Style helps with clarity, and that is useful, but it is not enough. They key is to present the right information to enable a particular user, with a particular background and set of skills, to complete a task. The goal is correct action, not necessarily understanding.
Too much information is almost as bad as not enough. At best it slows the reader down. At worst it saps their confidence. If they can't see the relevance of the information to their task, they begin to worry that they don't understand the task or the information.
The best way to learn to be a good tech writer, therefore, is to figure out what information people do and do not need. There are several ways to do this.
One it to do the task yourself and carefully note what information is needed -- particularly noting when you already know something that your target audience may not.
Another is to observe actual users, but this can be expensive.
A third is to study forums that cover products like yours and see what kinds of questions people ask and what kinds information they need before they are able to successfully solve their problem.
0 comment threads
0 comment threads