Hacker News Reader

Comment by cgh | Hacker News Reader

I'm sure you've seen it before, but The Economist's style guide is my usual resource: http://www.economist.com/styleguide/introduction

View on HN

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.

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.

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.)

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

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.

Try this one [0]. It's written by the CEO and Lead Writer of iFixit.

[0] - http://www.dozuki.com/Tech_Writing

Every time I read the Economist I wonder if their apparent compulsion to explain everything is some sort of in-joke.

"The US, a large north-american country,...".

Reply on news.ycombinator.com