: Re: 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

@Hamaas631

Vote Up Vote Down

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)

Login to post a comment!