Post History

Source: https://writers.stackexchange.com/a/7962
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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.

Original score: 5