2 ms·

This might not be so bad as a general guide to writing things like blog posts or whatever, but I'm specifically looking to get better at technical writing - e.g

by x1798DE 10y ago

This might not be so bad as a general guide to writing things like blog posts or whatever, but I'm specifically looking to get better at technical writing - e.g. writing software documentation. For example, the prohibition there on "jargon" words would probably come into conflict with the kind of precision you need in technical writing; I would expect the advice on something like that to be like, "where terms of art are required for the sake of precision, always make sure a definition is available, and link to it in hypertext formats" or "do not overload jargon words". Don't get me wrong, it's not like there's no overlap, but I'm looking for the equivalent of "Clean Code" for technical writing.

blisse 10y ago
But the rule is to avoid jargon if there's a better everyday equivalent, not to avoid jargon at all costs. There's no contradiction.
- x1798DE 10y ago
  Yes, I didn't intend that there was a contradiction, just that "jargon" and technical words are actually used more in technical writing than in other kinds of writing, and it can be tricky to understand where the line is, how to introduce these terms such that the reader is not confused by the unusual term (or by a common word used in an unusual way, like how in programming contexts the word "string" refers to a sequence of characters). Anyway, it's not that none of these principles apply, it's just that there are almost certainly many tweaks here and there and additional tips for people writing technical documentation - for example, almost no one sits down and reads the documentation for a library from "front to back", it is usually used in segments, which has implications about what you can expect your reader to know, and about how important navigation and organization of the document are. These are just some things that I've noticed as a consumer and producer of documentation, and I don't know that I even have good answers to most of them. (I hate to make it seem like I'm arguing the point that these more general writing guides are not good, I just want to clarify the kind of thing I'm looking to improve, for myself.)
  - blisse 10y ago
    No problem. I really enjoy MSDN documentation so I think imitating good guides or tutorials is a good starting point. As an aside I like the article How to Write Articles and Essays Quickly and Expertly[0] that was posted here a couple months back as well. [0] www.downes.ca/post/38526
fgimenez 10y ago
Check out Lyn Dupre's "Bugs in Writing." She was the department editor for Stanfords Biomedical Informatics program for several years and synthesized her work into that book. It's required reading for incoming students.
fgandiya 10y ago
Try this one [0]. It's written by the CEO and Lead Writer of iFixit. [0] - http://www.dozuki.com/Tech_Writing http://www.dozuki.com/Tech_Writing

by x1798DE 10y ago

blisse 10y ago

But the rule is to avoid jargon if there's a better everyday equivalent, not to avoid jargon at all costs. There's no contradiction.

x1798DE 10y ago
Yes, I didn't intend that there was a contradiction, just that "jargon" and technical words are actually used more in technical writing than in other kinds of writing, and it can be tricky to understand where the line is, how to introduce these terms such that the reader is not confused by the unusual term (or by a common word used in an unusual way, like how in programming contexts the word "string" refers to a sequence of characters). Anyway, it's not that none of these principles apply, it's just that there are almost certainly many tweaks here and there and additional tips for people writing technical documentation - for example, almost no one sits down and reads the documentation for a library from "front to back", it is usually used in segments, which has implications about what you can expect your reader to know, and about how important navigation and organization of the document are. These are just some things that I've noticed as a consumer and producer of documentation, and I don't know that I even have good answers to most of them. (I hate to make it seem like I'm arguing the point that these more general writing guides are not good, I just want to clarify the kind of thing I'm looking to improve, for myself.)
- blisse 10y ago
  No problem. I really enjoy MSDN documentation so I think imitating good guides or tutorials is a good starting point. As an aside I like the article How to Write Articles and Essays Quickly and Expertly[0] that was posted here a couple months back as well. [0] www.downes.ca/post/38526

fgimenez 10y ago

Check out Lyn Dupre's "Bugs in Writing." She was the department editor for Stanfords Biomedical Informatics program for several years and synthesized her work into that book. It's required reading for incoming students.

fgandiya 10y ago

Try this one [0]. It's written by the CEO and Lead Writer of iFixit. [0] - http://www.dozuki.com/Tech_Writing http://www.dozuki.com/Tech_Writing