Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Write Like You Code

chrisbehan.ca

Post reply on HN
Print view View original

41–50 of 71 posts

Re: Write Like You Code

#41

Post by erwincoumans »

KineticLensman wrote: post #16
praptak wrote: post #14

I recently did a short training on technical writing. One piece of advice stuck with me because it is a) counter intuitive and b) not followed widely enough. It can also be said to follow "write like you code", so here it goes: When writing a technical document, stick to one word per concept. Say you are using "throughput" for how many requests per seconds a service handles in a given period of time. Don't rename it…

> When writing a technical document, stick to one word per concept Yes, this is absolutely critical. As a tech reviewer I once came across a doc that used no fewer than seven different terms for the same underlying thing. Part of the problem was that it has been written by at least two authors over a couple of months. At least one of the authors admitted that they hadn't take the time to remind themselves what had al…

Take the word 'non-fiction' next to 'tech docs' as an example of not using one word per concept. Did you mean tech docs as a subset of non-fiction? English is my second language and I always have to think twice translating fiction (into fantasy) and non-fiction (into real).

Re: Write Like You Code

#42

Post by pbronez »

JamilD wrote: post #17
kranner wrote: post #3

This writing advice -- recycled from newspaper house style guides -- to use only simple and common words in efficient sentences is becoming almost universal, and yet "good writing" doesn't always obey these rules. Sometimes you need a certain obliqueness and sesquipedalianism to convey a certain effect that simple directness can't achieve. To paraphrase Mark Twain, sometimes you need the right word and not its second…

It's easier to hide bad writing with more difficult words. When writing in a way that's easily understandable, bad writing or arguments that don't make sense become much more evident. I see it as a progression. It's easy to lie to yourself and think you're a good writer by clouding your prose with difficult-to-understand sentences. I think once you've mastered writing simply, you can be confident that you're able to…

I agree with this. Most people need to simply their writing and convey their ideas more clearly. Once you've mastered that, you can explore more sophisticated prose.

Re: Write Like You Code

#43

Post by lkxijlewlf »

praptak wrote: post #14

I recently did a short training on technical writing. One piece of advice stuck with me because it is a) counter intuitive and b) not followed widely enough. It can also be said to follow "write like you code", so here it goes: When writing a technical document, stick to one word per concept. Say you are using "throughput" for how many requests per seconds a service handles in a given period of time. Don't rename it…

Another thing that annoyed me in tech writing when I was still fresh in the field was when all the examples built upon the previous and then out of nowhere the next example was different. IE: some author has spent a couple chapters building up, I dunno, some coffee shop website but now that they want to discuss concurrency they're going to switch to a CLI app that hits Wx sites for the current weather.

Re: Write Like You Code

#44

Post by musingsole »

marcellus23 wrote: post #30
kqr wrote: post #19

Earlier quoted context omitted.

This is not just for technical writing and coding. It goes for communication and thinking in a technical context as well. You're going to make so many design mistakes if you use several words for one concept, or the same word for multiple concepts. I know the Sapir-Whorf hypothesis is discounted by linguists, but I believe I have loads of first-hand experience showing how word choice affects design decisions in fairl…

I know it’s not the point of your comment, but the Sapir-Whorf hypothesis is about how your language itself structures your thinking, not word or grammar choice in individual utterances or writings made by an individual.

I don't see your correction. Individual word or grammar preferences are to Sapir-Whorf what tactics are to strategy.

Re: Write Like You Code

#45

Post by KineticLensman »

erwincoumans wrote: post #41
KineticLensman wrote: post #16

Earlier quoted context omitted.

> When writing a technical document, stick to one word per concept Yes, this is absolutely critical. As a tech reviewer I once came across a doc that used no fewer than seven different terms for the same underlying thing. Part of the problem was that it has been written by at least two authors over a couple of months. At least one of the authors admitted that they hadn't take the time to remind themselves what had al…

Take the word 'non-fiction' next to 'tech docs' as an example of not using one word per concept. Did you mean tech docs as a subset of non-fiction? English is my second language and I always have to think twice translating fiction (into fantasy) and non-fiction (into real).

> Take the word 'non-fiction' next to 'tech docs' as an example of not using one word per concept

Good point! I'm guilty of the problem myself. I did mean tech docs as a subset of non-fiction. In these terms, I would now state that technical docs should use 'one term per concept', but that non-fiction doesn't have to as long as some ambiguity is acceptable.

Re: Write Like You Code

#46

Post by codazoda »

praptak wrote: post #14

I recently did a short training on technical writing. One piece of advice stuck with me because it is a) counter intuitive and b) not followed widely enough. It can also be said to follow "write like you code", so here it goes: When writing a technical document, stick to one word per concept. Say you are using "throughput" for how many requests per seconds a service handles in a given period of time. Don't rename it…

Interesting. I’m guilty of this in my online writing in the name of SEO. After all, my readers might search for either term. This probably makes my writing worse.

Re: Write Like You Code

#47

Post by bryanrasmussen »

hutzlibu wrote: post #15
kranner wrote: post #3

This writing advice -- recycled from newspaper house style guides -- to use only simple and common words in efficient sentences is becoming almost universal, and yet "good writing" doesn't always obey these rules. Sometimes you need a certain obliqueness and sesquipedalianism to convey a certain effect that simple directness can't achieve. To paraphrase Mark Twain, sometimes you need the right word and not its second…

"- to use only simple and common words in efficient sentences is becoming almost universal, and yet "good writing" doesn't always obey these rules." I would say it depends what you write and to whom. If your target is "the internet" where most people only speak simple english - you absolutely want to use simple english, if you want to reach more people. And also in everyday life I made an effort to value clarity and…

>And I would say, the whole world is in a state of confusion caused by missunderstanding. If people would speak and write a bit more clean and clearly (like good code) I think everyone would benefit.

many professions have concepts that are complicated to understand for people outside the profession and as such develop their own jargon.

The development of jargon that is perceived as unfriendly and complicated to people outside the profession is often driven by the need for greater clarity inside the profession.

Finally in the case of programming languages and clarity arguments, clarity relates to your expertise, the less expert phrasing is sometimes overly verbose and destructive to quick comprehension, while the expert phrasing may seem incomprehensible to the non-expert.

Re: Write Like You Code

#48

Post by mhb »

Unless the author's intent is to simultaneously give advice about how to code, the essay could be improved by removing the references to coding.

For example: Good writing is like good code, it's simple, efficient, and structured.

Good writing is simple, efficient, and structured.

Re: Write Like You Code

#49

Post by fullstackchris »

barrkel wrote: post #36

Long functions don't necessarily make for bad code. If there aren't long loops or long conditionals, long functions can reveal a lot of structure without the cognitive overhead of many single-use functions. Good code uses abstraction judiciously. The same in prose leads to parentheticals and rabbit-holes. Good code is both easy to read and easy to modify, but making it easy to modify without losing much legibility is…

Agreed with all points. I only read into the first few paragraphs and immediately found it to be overly simplifying the processes of both writing and programming. Good advice for beginners perhaps, but definitely not rules to live by.

Re: Write Like You Code

#50

Post by [deleted] »

KineticLensman wrote: post #45
erwincoumans wrote: post #41

Earlier quoted context omitted.

Take the word 'non-fiction' next to 'tech docs' as an example of not using one word per concept. Did you mean tech docs as a subset of non-fiction? English is my second language and I always have to think twice translating fiction (into fantasy) and non-fiction (into real).

> Take the word 'non-fiction' next to 'tech docs' as an example of not using one word per concept Good point! I'm guilty of the problem myself. I did mean tech docs as a subset of non-fiction. In these terms, I would now state that technical docs should use 'one term per concept', but that non-fiction doesn't have to as long as some ambiguity is acceptable.

[deleted]
Post reply on HN